blob: 5cb961132de1a2131add5c6e9e989e6caaa13a04 [file] [log] [blame]
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001*eval.txt* For Vim version 7.0aa. Last change: 2005 Jan 25
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 Moolenaard8b02732005-01-14 21:48:43 +000012done, the features in this document are not available. See |+eval| and
13|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|
18 1.3 Lists |List|
Bram Moolenaard8b02732005-01-14 21:48:43 +000019 1.4 Dictionaries |Dictionaries|
20 1.5 More about variables |more-variables|
Bram Moolenaar13065c42005-01-08 16:08:21 +0000212. Expression syntax |expression-syntax|
223. Internal variable |internal-variables|
234. Builtin Functions |functions|
245. Defining functions |user-functions|
256. Curly braces names |curly-braces-names|
267. Commands |expression-commands|
278. Exception handling |exception-handling|
289. Examples |eval-examples|
2910. No +eval feature |no-eval-feature|
3011. The sandbox |eval-sandbox|
Bram Moolenaar071d4272004-06-13 20:20:40 +000031
32{Vi does not have any of these commands}
33
34==============================================================================
351. Variables *variables*
36
Bram Moolenaar13065c42005-01-08 16:08:21 +0000371.1 Variable types ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000038 *E712*
Bram Moolenaar13065c42005-01-08 16:08:21 +000039There are four types of variables:
Bram Moolenaar071d4272004-06-13 20:20:40 +000040
Bram Moolenaard8b02732005-01-14 21:48:43 +000041Number A 32 bit signed number.
42 Examples: -123 0x10 0177
43
44String A NUL terminated string of 8-bit unsigned characters (bytes).
45 Examples: "ab\txx\"--" 'x-z''a,c'
46
47Funcref A reference to a function |Funcref|.
48 Example: function("strlen")
49
50List An ordered sequence of items |List|.
51 Example: [1, 2, ['a', 'b']]
Bram Moolenaar071d4272004-06-13 20:20:40 +000052
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000053The Number and String types are converted automatically, depending on how they
54are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000055
56Conversion from a Number to a String is by making the ASCII representation of
57the Number. Examples: >
58 Number 123 --> String "123"
59 Number 0 --> String "0"
60 Number -1 --> String "-1"
61
62Conversion from a String to a Number is done by converting the first digits
63to a number. Hexadecimal "0xf9" and Octal "017" numbers are recognized. If
64the String doesn't start with digits, the result is zero. Examples: >
65 String "456" --> Number 456
66 String "6bar" --> Number 6
67 String "foo" --> Number 0
68 String "0xf1" --> Number 241
69 String "0100" --> Number 64
70 String "-8" --> Number -8
71 String "+8" --> Number 0
72
73To force conversion from String to Number, add zero to it: >
74 :echo "0100" + 0
75
76For boolean operators Numbers are used. Zero is FALSE, non-zero is TRUE.
77
78Note that in the command >
79 :if "foo"
80"foo" is converted to 0, which means FALSE. To test for a non-empty string,
81use strlen(): >
82 :if strlen("foo")
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000083< *E728* *E729* *E730* *E731*
Bram Moolenaar13065c42005-01-08 16:08:21 +000084List and Funcref types are not automatically converted.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000085
Bram Moolenaar13065c42005-01-08 16:08:21 +000086 *E706*
87You will get an error if you try to change the type of a variable. You need
88to |:unlet| it first to avoid this error. String and Number are considered
Bram Moolenaard8b02732005-01-14 21:48:43 +000089equivalent though. Consider this sequence of commands: >
Bram Moolenaar13065c42005-01-08 16:08:21 +000090 :let l = "string"
Bram Moolenaar9588a0f2005-01-08 21:45:39 +000091 :let l = 44 " changes type from String to Number
Bram Moolenaar13065c42005-01-08 16:08:21 +000092 :let l = [1, 2, 3] " error!
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000093
Bram Moolenaar13065c42005-01-08 16:08:21 +000094
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000951.2 Function references ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000096 *Funcref* *E695* *E703* *E718*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000097A Funcref variable is obtained with the |function()| function. It can be used
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000098in an expression in the place of a function name, before the parenthesis
99around the arguments, to invoke the function it refers to. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000100
101 :let Fn = function("MyFunc")
102 :echo Fn()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000103< *E704* *E705* *E707*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000104A Funcref variable must start with a capital, "s:", "w:" or "b:". You cannot
105have both a Funcref variable and a function with the same name.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000106
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000107A special case is defining a function and directly assigning its Funcref to a
108Dictionary entry. Example: >
109 :function dict.init() dict
110 : let self.val = 0
111 :endfunction
112
113The key of the Dictionary can start with a lower case letter. The actual
114function name is not used here. Also see |numbered-function|.
115
116A Funcref can also be used with the |:call| command: >
117 :call Fn()
118 :call dict.init()
Bram Moolenaar13065c42005-01-08 16:08:21 +0000119
120The name of the referenced function can be obtained with |string()|. >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000121 :let func = string(Fn)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000122
123You can use |call()| to invoke a Funcref and use a list variable for the
124arguments: >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000125 :let r = call(Fn, mylist)
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000126
127
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001281.3 Lists ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000129 *List* *E686*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000130A List is an ordered sequence of items. An item can be of any type. Items
131can be accessed by their index number. Items can be added and removed at any
132position in the sequence.
133
Bram Moolenaar13065c42005-01-08 16:08:21 +0000134
135List creation ~
136 *E696* *E697*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000137A List is created with a comma separated list of items in square brackets.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000138Examples: >
139 :let mylist = [1, two, 3, "four"]
140 :let emptylist = []
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000141
142An item can be any expression. Using a List for an item creates a
Bram Moolenaar13065c42005-01-08 16:08:21 +0000143nested List: >
144 :let nestlist = [[11, 12], [21, 22], [31, 32]]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000145
146An extra comma after the last item is ignored.
147
Bram Moolenaar13065c42005-01-08 16:08:21 +0000148
149List index ~
150 *list-index* *E684*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000151An item in the List can be accessed by putting the index in square brackets
Bram Moolenaar13065c42005-01-08 16:08:21 +0000152after the List. Indexes are zero-based, thus the first item has index zero. >
153 :let item = mylist[0] " get the first item: 1
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000154 :let item = mylist[2] " get the third item: 3
Bram Moolenaar13065c42005-01-08 16:08:21 +0000155
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000156When the resulting item is a list this can be repeated: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000157 :let item = nestlist[0][1] " get the first list, second item: 12
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000158<
Bram Moolenaar13065c42005-01-08 16:08:21 +0000159A negative index is counted from the end. Index -1 refers to the last item in
160the List, -2 to the last but one item, etc. >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000161 :let last = mylist[-1] " get the last item: "four"
162
Bram Moolenaar13065c42005-01-08 16:08:21 +0000163To avoid an error for an invalid index use the |get()| function. When an item
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000164is not available it returns zero or the default value you specify: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000165 :echo get(mylist, idx)
166 :echo get(mylist, idx, "NONE")
167
168
169List concatenation ~
170
171Two lists can be concatenated with the "+" operator: >
172 :let longlist = mylist + [5, 6]
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000173 :let mylist += [7, 8]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000174
175To prepend or append an item turn the item into a list by putting [] around
176it. To change a list in-place see |list-modification| below.
177
178
179Sublist ~
180
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000181A part of the List can be obtained by specifying the first and last index,
182separated by a colon in square brackets: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000183 :let shortlist = mylist[2:-1] " get List [3, "four"]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000184
185Omitting the first index is similar to zero. Omitting the last index is
186similar to -1. The difference is that there is no error if the items are not
187available. >
Bram Moolenaar540d6e32005-01-09 21:20:18 +0000188 :let endlist = mylist[2:] " from item 2 to the end: [3, "four"]
189 :let shortlist = mylist[2:2] " List with one item: [3]
190 :let otherlist = mylist[:] " make a copy of the List
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000191
Bram Moolenaard8b02732005-01-14 21:48:43 +0000192The second index can be just before the first index. In that case the result
193is an empty list. If the second index is lower, this results in an error. >
194 :echo mylist[2:1] " result: []
195 :echo mylist[2:0] " error!
196
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000197
Bram Moolenaar13065c42005-01-08 16:08:21 +0000198List identity ~
Bram Moolenaard8b02732005-01-14 21:48:43 +0000199 *list-identity*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000200When variable "aa" is a list and you assign it to another variable "bb", both
201variables refer to the same list. Thus changing the list "aa" will also
202change "bb": >
203 :let aa = [1, 2, 3]
204 :let bb = aa
205 :call add(aa, 4)
206 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000207< [1, 2, 3, 4]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000208
209Making a copy of a list is done with the |copy()| function. Using [:] also
210works, as explained above. This creates a shallow copy of the list: Changing
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000211a list item in the list will also change the item in the copied list: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000212 :let aa = [[1, 'a'], 2, 3]
213 :let bb = copy(aa)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000214 :call add(aa, 4)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000215 :let aa[0][1] = 'aaa'
216 :echo aa
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000217< [[1, aaa], 2, 3, 4] >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000218 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000219< [[1, aaa], 2, 3]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000220
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000221To make a completely independent list use |deepcopy()|. This also makes a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000222copy of the values in the list, recursively. Up to a hundred levels deep.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000223
224The operator "is" can be used to check if two variables refer to the same
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000225List. "isnot" does the opposite. In contrast "==" compares if two lists have
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000226the same value. >
227 :let alist = [1, 2, 3]
228 :let blist = [1, 2, 3]
229 :echo alist is blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000230< 0 >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000231 :echo alist == blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000232< 1
Bram Moolenaar13065c42005-01-08 16:08:21 +0000233
234
235List unpack ~
236
237To unpack the items in a list to individual variables, put the variables in
238square brackets, like list items: >
239 :let [var1, var2] = mylist
240
241When the number of variables does not match the number of items in the list
242this produces an error. To handle any extra items from the list append ";"
243and a variable name: >
244 :let [var1, var2; rest] = mylist
245
246This works like: >
247 :let var1 = mylist[0]
248 :let var2 = mylist[1]
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000249 :let rest = mylist[2:]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000250
251Except that there is no error if there are only two items. "rest" will be an
252empty list then.
253
254
255List modification ~
256 *list-modification*
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000257To change a specific item of a list use |:let| this way: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000258 :let list[4] = "four"
259 :let listlist[0][3] = item
260
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000261To change part of a list you can specify the first and last item to be
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000262modified. The value must at least have the number of items in the range: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000263 :let list[3:5] = [3, 4, 5]
264
Bram Moolenaar13065c42005-01-08 16:08:21 +0000265Adding and removing items from a list is done with functions. Here are a few
266examples: >
267 :call insert(list, 'a') " prepend item 'a'
268 :call insert(list, 'a', 3) " insert item 'a' before list[3]
269 :call add(list, "new") " append String item
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000270 :call add(list, [1, 2]) " append a List as one new item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000271 :call extend(list, [1, 2]) " extend the list with two more items
272 :let i = remove(list, 3) " remove item 3
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000273 :unlet list[3] " idem
Bram Moolenaar13065c42005-01-08 16:08:21 +0000274 :let l = remove(list, 3, -1) " remove items 3 to last item
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000275 :unlet list[3 : ] " idem
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000276 :call filter(list, 'v:val !~ "x"') " remove items with an 'x'
Bram Moolenaar13065c42005-01-08 16:08:21 +0000277
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000278Changing the order of items in a list: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000279 :call sort(list) " sort a list alphabetically
280 :call reverse(list) " reverse the order of items
281
Bram Moolenaar13065c42005-01-08 16:08:21 +0000282
283For loop ~
284
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000285The |:for| loop executes commands for each item in a list. A variable is set
286to each item in the list in sequence. Example: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000287 :for item in mylist
288 : call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000289 :endfor
290
291This works like: >
292 :let index = 0
293 :while index < len(mylist)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000294 : let item = mylist[index]
295 : :call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000296 : let index = index + 1
297 :endwhile
298
299Note that all items in the list should be of the same type, otherwise this
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000300results in error |E706|. To avoid this |:unlet| the variable at the end of
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000301the loop.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000302
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000303If all you want to do is modify each item in the list then the |map()|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000304function will be a simpler method than a for loop.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000305
Bram Moolenaar13065c42005-01-08 16:08:21 +0000306Just like the |:let| command, |:for| also accepts a list of variables. This
307requires the argument to be a list of lists. >
308 :for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
309 : call Doit(lnum, col)
310 :endfor
311
312This works like a |:let| command is done for each list item. Again, the types
313must remain the same to avoid an error.
314
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000315It is also possible to put remaining items in a List variable: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000316 :for [i, j; rest] in listlist
317 : call Doit(i, j)
318 : if !empty(rest)
319 : echo "remainder: " . string(rest)
320 : endif
321 :endfor
322
323
324List functions ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000325 *E714*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000326Functions that are useful with a List: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000327 :let r = call(funcname, list) " call a function with an argument list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000328 :if empty(list) " check if list is empty
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000329 :let l = len(list) " number of items in list
330 :let big = max(list) " maximum value in list
331 :let small = min(list) " minimum value in list
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000332 :let xs = count(list, 'x') " count nr of times 'x' appears in list
333 :let i = index(list, 'x') " index of first 'x' in list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000334 :let lines = getline(1, 10) " get ten text lines from buffer
335 :call append('$', lines) " append text lines in buffer
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000336 :let list = split("a b c") " create list from items in a string
337 :let string = join(list, ', ') " create string from list items
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000338 :let s = string(list) " String representation of list
339 :call map(list, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000340
341
Bram Moolenaard8b02732005-01-14 21:48:43 +00003421.4 Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000343 *Dictionaries* *Dictionary*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000344A Dictionary is an associative array: Each entry has a key and a value. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000345entry can be located with the key. The entries are stored without a specific
346ordering.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000347
348
349Dictionary creation ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000350 *E720* *E721* *E722* *E723*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000351A Dictionary is created with a comma separated list of entries in curly
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000352braces. Each entry has a key and a value, separated by a colon. Each key can
353only appear once. Examples: >
Bram Moolenaard8b02732005-01-14 21:48:43 +0000354 :let mydict = {1: 'one', 2: 'two', 3: 'three'}
355 :let emptydict = {}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000356< *E713* *E716* *E717*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000357A key is always a String. You can use a Number, it will be converted to a
358String automatically. Thus the String '4' and the number 4 will find the same
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000359entry. Note that the String '04' and the Number 04 are different, since the
360Number will be converted to the String '4'.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000361
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000362A value can be any expression. Using a Dictionary for a value creates a
Bram Moolenaard8b02732005-01-14 21:48:43 +0000363nested Dictionary: >
364 :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}}
365
366An extra comma after the last entry is ignored.
367
368
369Accessing entries ~
370
371The normal way to access an entry is by putting the key in square brackets: >
372 :let val = mydict["one"]
373 :let mydict["four"] = 4
374
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000375You can add new entries to an existing Dictionary this way, unlike Lists.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000376
377For keys that consist entirely of letters, digits and underscore the following
378form can be used |expr-entry|: >
379 :let val = mydict.one
380 :let mydict.four = 4
381
382Since an entry can be any type, also a List and a Dictionary, the indexing and
383key lookup can be repeated: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000384 :echo dict.key[idx].key
Bram Moolenaard8b02732005-01-14 21:48:43 +0000385
386
387Dictionary to List conversion ~
388
389You may want to loop over the entries in a dictionary. For this you need to
390turn the Dictionary into a List and pass it to |:for|.
391
392Most often you want to loop over the keys, using the |keys()| function: >
393 :for key in keys(mydict)
394 : echo key . ': ' . mydict[key]
395 :endfor
396
397The List of keys is unsorted. You may want to sort them first: >
398 :for key in sort(keys(mydict))
399
400To loop over the values use the |values()| function: >
401 :for v in values(mydict)
402 : echo "value: " . v
403 :endfor
404
405If you want both the key and the value use the |items()| function. It returns
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000406a List in which each item is a List with two items, the key and the value: >
Bram Moolenaard8b02732005-01-14 21:48:43 +0000407 :for entry in items(mydict)
408 : echo entry[0] . ': ' . entry[1]
409 :endfor
410
411
412Dictionary identity ~
413
414Just like Lists you need to use |copy()| and |deepcopy()| to make a copy of a
415Dictionary. Otherwise, assignment results in referring to the same
416Dictionary: >
417 :let onedict = {'a': 1, 'b': 2}
418 :let adict = onedict
419 :let adict['a'] = 11
420 :echo onedict['a']
421 11
422
423For more info see |list-identity|.
424
425
426Dictionary modification ~
427 *dict-modification*
428To change an already existing entry of a Dictionary, or to add a new entry,
429use |:let| this way: >
430 :let dict[4] = "four"
431 :let dict['one'] = item
432
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000433Removing an entry from a Dictionary is done with |remove()| or |:unlet|.
434Three ways to remove the entry with key "aaa" from dict: >
435 :let i = remove(dict, 'aaa')
436 :unlet dict.aaa
437 :unlet dict['aaa']
Bram Moolenaard8b02732005-01-14 21:48:43 +0000438
439Merging a Dictionary with another is done with |extend()|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000440 :call extend(adict, bdict)
441This extends adict with all entries from bdict. Duplicate keys cause entries
442in adict to be overwritten. An optional third argument can change this.
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000443Note that the order of entries in a Dictionary is irrelevant, thus don't
444expect ":echo adict" to show the items from bdict after the older entries in
445adict.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000446
447Weeding out entries from a Dictionary can be done with |filter()|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000448 :call filter(dict 'v:val =~ "x"')
449This removes all entries from "dict" with a value not matching 'x'.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000450
451
452Dictionary function ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000453 *Dictionary-function* *self* *E725*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000454When a function is defined with the "dict" attribute it can be used in a
455special way with a dictionary. Example: >
456 :function Mylen() dict
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000457 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000458 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000459 :let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}
460 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000461
462This is like a method in object oriented programming. The entry in the
463Dictionary is a |Funcref|. The local variable "self" refers to the dictionary
464the function was invoked from.
465
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000466It is also possible to add a function without the "dict" attribute as a
467Funcref to a Dictionary, but the "self" variable is not available then.
468
469 *numbered-function*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000470To avoid the extra name for the function it can be defined and directly
471assigned to a Dictionary in this way: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000472 :let mydict = {'data': [0, 1, 2, 3]}
473 :function mydict.len() dict
474 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000475 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000476 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000477
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000478The function will then get a number and the value of dict.len is a |Funcref|
479that references this function. The function can only be used through a
480|Funcref|. It will automatically be deleted when there is no |Funcref|
481remaining that refers to it.
482
483It is not necessary to use the "dict" attribute for a numbered function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000484
485
486Functions for Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000487 *E715*
488Functions that can be used with a Dictionary: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000489 :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo"
490 :if empty(dict) " TRUE if dict is empty
491 :let l = len(dict) " number of items in dict
492 :let big = max(dict) " maximum value in dict
493 :let small = min(dict) " minimum value in dict
494 :let xs = count(dict, 'x') " count nr of times 'x' appears in dict
495 :let s = string(dict) " String representation of dict
496 :call map(dict, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaard8b02732005-01-14 21:48:43 +0000497
498
4991.5 More about variables ~
Bram Moolenaar13065c42005-01-08 16:08:21 +0000500 *more-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000501If you need to know the type of a variable or expression, use the |type()|
502function.
503
504When the '!' flag is included in the 'viminfo' option, global variables that
505start with an uppercase letter, and don't contain a lowercase letter, are
506stored in the viminfo file |viminfo-file|.
507
508When the 'sessionoptions' option contains "global", global variables that
509start with an uppercase letter and contain at least one lowercase letter are
510stored in the session file |session-file|.
511
512variable name can be stored where ~
513my_var_6 not
514My_Var_6 session file
515MY_VAR_6 viminfo file
516
517
518It's possible to form a variable name with curly braces, see
519|curly-braces-names|.
520
521==============================================================================
5222. Expression syntax *expression-syntax*
523
524Expression syntax summary, from least to most significant:
525
526|expr1| expr2 ? expr1 : expr1 if-then-else
527
528|expr2| expr3 || expr3 .. logical OR
529
530|expr3| expr4 && expr4 .. logical AND
531
532|expr4| expr5 == expr5 equal
533 expr5 != expr5 not equal
534 expr5 > expr5 greater than
535 expr5 >= expr5 greater than or equal
536 expr5 < expr5 smaller than
537 expr5 <= expr5 smaller than or equal
538 expr5 =~ expr5 regexp matches
539 expr5 !~ expr5 regexp doesn't match
540
541 expr5 ==? expr5 equal, ignoring case
542 expr5 ==# expr5 equal, match case
543 etc. As above, append ? for ignoring case, # for
544 matching case
545
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000546 expr5 is expr5 same List instance
547 expr5 isnot expr5 different List instance
548
549|expr5| expr6 + expr6 .. number addition or list concatenation
Bram Moolenaar071d4272004-06-13 20:20:40 +0000550 expr6 - expr6 .. number subtraction
551 expr6 . expr6 .. string concatenation
552
553|expr6| expr7 * expr7 .. number multiplication
554 expr7 / expr7 .. number division
555 expr7 % expr7 .. number modulo
556
557|expr7| ! expr7 logical NOT
558 - expr7 unary minus
559 + expr7 unary plus
Bram Moolenaar071d4272004-06-13 20:20:40 +0000560
Bram Moolenaar071d4272004-06-13 20:20:40 +0000561
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000562|expr8| expr8[expr1] byte of a String or item of a List
563 expr8[expr1 : expr1] substring of a String or sublist of a List
564 expr8.name entry in a Dictionary
565 expr8(expr1, ...) function call with Funcref variable
566
567|expr9| number number constant
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000568 "string" string constant, backslash is special
Bram Moolenaard8b02732005-01-14 21:48:43 +0000569 'string' string constant, ' is doubled
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000570 [expr1, ...] List
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000571 {expr1: expr1, ...} Dictionary
Bram Moolenaar071d4272004-06-13 20:20:40 +0000572 &option option value
573 (expr1) nested expression
574 variable internal variable
575 va{ria}ble internal variable with curly braces
576 $VAR environment variable
577 @r contents of register 'r'
578 function(expr1, ...) function call
579 func{ti}on(expr1, ...) function call with curly braces
580
581
582".." indicates that the operations in this level can be concatenated.
583Example: >
584 &nu || &list && &shell == "csh"
585
586All expressions within one level are parsed from left to right.
587
588
589expr1 *expr1* *E109*
590-----
591
592expr2 ? expr1 : expr1
593
594The expression before the '?' is evaluated to a number. If it evaluates to
595non-zero, the result is the value of the expression between the '?' and ':',
596otherwise the result is the value of the expression after the ':'.
597Example: >
598 :echo lnum == 1 ? "top" : lnum
599
600Since the first expression is an "expr2", it cannot contain another ?:. The
601other two expressions can, thus allow for recursive use of ?:.
602Example: >
603 :echo lnum == 1 ? "top" : lnum == 1000 ? "last" : lnum
604
605To keep this readable, using |line-continuation| is suggested: >
606 :echo lnum == 1
607 :\ ? "top"
608 :\ : lnum == 1000
609 :\ ? "last"
610 :\ : lnum
611
612
613expr2 and expr3 *expr2* *expr3*
614---------------
615
616 *expr-barbar* *expr-&&*
617The "||" and "&&" operators take one argument on each side. The arguments
618are (converted to) Numbers. The result is:
619
620 input output ~
621n1 n2 n1 || n2 n1 && n2 ~
622zero zero zero zero
623zero non-zero non-zero zero
624non-zero zero non-zero zero
625non-zero non-zero non-zero non-zero
626
627The operators can be concatenated, for example: >
628
629 &nu || &list && &shell == "csh"
630
631Note that "&&" takes precedence over "||", so this has the meaning of: >
632
633 &nu || (&list && &shell == "csh")
634
635Once the result is known, the expression "short-circuits", that is, further
636arguments are not evaluated. This is like what happens in C. For example: >
637
638 let a = 1
639 echo a || b
640
641This is valid even if there is no variable called "b" because "a" is non-zero,
642so the result must be non-zero. Similarly below: >
643
644 echo exists("b") && b == "yes"
645
646This is valid whether "b" has been defined or not. The second clause will
647only be evaluated if "b" has been defined.
648
649
650expr4 *expr4*
651-----
652
653expr5 {cmp} expr5
654
655Compare two expr5 expressions, resulting in a 0 if it evaluates to false, or 1
656if it evaluates to true.
657
658 *expr-==* *expr-!=* *expr->* *expr->=*
659 *expr-<* *expr-<=* *expr-=~* *expr-!~*
660 *expr-==#* *expr-!=#* *expr->#* *expr->=#*
661 *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#*
662 *expr-==?* *expr-!=?* *expr->?* *expr->=?*
663 *expr-<?* *expr-<=?* *expr-=~?* *expr-!~?*
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000664 *expr-is*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000665 use 'ignorecase' match case ignore case ~
666equal == ==# ==?
667not equal != !=# !=?
668greater than > ># >?
669greater than or equal >= >=# >=?
670smaller than < <# <?
671smaller than or equal <= <=# <=?
672regexp matches =~ =~# =~?
673regexp doesn't match !~ !~# !~?
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000674same instance is
675different instance isnot
Bram Moolenaar071d4272004-06-13 20:20:40 +0000676
677Examples:
678"abc" ==# "Abc" evaluates to 0
679"abc" ==? "Abc" evaluates to 1
680"abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise
681
Bram Moolenaar13065c42005-01-08 16:08:21 +0000682 *E691* *E692*
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000683A List can only be compared with a List and only "equal", "not equal" and "is"
684can be used. This compares the values of the list, recursively. Ignoring
685case means case is ignored when comparing item values.
686
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000687 *E735* *E736*
688A Dictionary can only be compared with a Dictionary and only "equal", "not
689equal" and "is" can be used. This compares the key/values of the Dictionary,
690recursively. Ignoring case means case is ignored when comparing item values.
691
Bram Moolenaar13065c42005-01-08 16:08:21 +0000692 *E693* *E694*
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000693A Funcref can only be compared with a Funcref and only "equal" and "not equal"
694can be used. Case is never ignored.
695
696When using "is" or "isnot" with a List this checks if the expressions are
697referring to the same List instance. A copy of a List is different from the
698original List. When using "is" without a List it is equivalent to using
699"equal", using "isnot" equivalent to using "not equal". Except that a
700different type means the values are different. "4 == '4'" is true, "4 is '4'"
701is false.
702
Bram Moolenaar071d4272004-06-13 20:20:40 +0000703When comparing a String with a Number, the String is converted to a Number,
704and the comparison is done on Numbers. This means that "0 == 'x'" is TRUE,
705because 'x' converted to a Number is zero.
706
707When comparing two Strings, this is done with strcmp() or stricmp(). This
708results in the mathematical difference (comparing byte values), not
709necessarily the alphabetical difference in the local language.
710
711When using the operators with a trailing '#", or the short version and
712'ignorecase' is off, the comparing is done with strcmp().
713
714When using the operators with a trailing '?', or the short version and
715'ignorecase' is set, the comparing is done with stricmp().
716
717The "=~" and "!~" operators match the lefthand argument with the righthand
718argument, which is used as a pattern. See |pattern| for what a pattern is.
719This matching is always done like 'magic' was set and 'cpoptions' is empty, no
720matter what the actual value of 'magic' or 'cpoptions' is. This makes scripts
721portable. To avoid backslashes in the regexp pattern to be doubled, use a
722single-quote string, see |literal-string|.
723Since a string is considered to be a single line, a multi-line pattern
724(containing \n, backslash-n) will not match. However, a literal NL character
725can be matched like an ordinary character. Examples:
726 "foo\nbar" =~ "\n" evaluates to 1
727 "foo\nbar" =~ "\\n" evaluates to 0
728
729
730expr5 and expr6 *expr5* *expr6*
731---------------
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000732expr6 + expr6 .. Number addition or List concatenation *expr-+*
733expr6 - expr6 .. Number subtraction *expr--*
734expr6 . expr6 .. String concatenation *expr-.*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000735
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000736For Lists only "+" is possible and then both expr6 must be a list. The result
737is a new list with the two lists Concatenated.
738
739expr7 * expr7 .. number multiplication *expr-star*
740expr7 / expr7 .. number division *expr-/*
741expr7 % expr7 .. number modulo *expr-%*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000742
743For all, except ".", Strings are converted to Numbers.
744
745Note the difference between "+" and ".":
746 "123" + "456" = 579
747 "123" . "456" = "123456"
748
749When the righthand side of '/' is zero, the result is 0x7fffffff.
750When the righthand side of '%' is zero, the result is 0.
751
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000752None of these work for Funcrefs.
753
Bram Moolenaar071d4272004-06-13 20:20:40 +0000754
755expr7 *expr7*
756-----
757! expr7 logical NOT *expr-!*
758- expr7 unary minus *expr-unary--*
759+ expr7 unary plus *expr-unary-+*
760
761For '!' non-zero becomes zero, zero becomes one.
762For '-' the sign of the number is changed.
763For '+' the number is unchanged.
764
765A String will be converted to a Number first.
766
767These three can be repeated and mixed. Examples:
768 !-1 == 0
769 !!8 == 1
770 --9 == 9
771
772
773expr8 *expr8*
774-----
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000775expr8[expr1] item of String or List *expr-[]* *E111*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000776
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000777If expr8 is a Number or String this results in a String that contains the
778expr1'th single byte from expr8. expr8 is used as a String, expr1 as a
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000779Number. Note that this doesn't recognize multi-byte encodings.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000780
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000781Index zero gives the first character. This is like it works in C. Careful:
782text column numbers start with one! Example, to get the character under the
783cursor: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000784 :let c = getline(line("."))[col(".") - 1]
785
786If the length of the String is less than the index, the result is an empty
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000787String. A negative index always results in an empty string (reason: backwards
788compatibility). Use [-1:] to get the last byte.
789
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000790If expr8 is a List then it results the item at index expr1. See |list-index|
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000791for possible index values. If the index is out of range this results in an
792error. Example: >
793 :let item = mylist[-1] " get last item
794
795Generally, if a List index is equal to or higher than the length of the List,
796or more negative than the length of the List, this results in an error.
797
Bram Moolenaard8b02732005-01-14 21:48:43 +0000798
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000799expr8[expr1a : expr1b] substring or sublist *expr-[:]*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000800
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000801If expr8 is a Number or String this results in the substring with the bytes
802from expr1a to and including expr1b. expr8 is used as a String, expr1a and
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000803expr1b are used as a Number. Note that this doesn't recognize multi-byte
804encodings.
805
806If expr1a is omitted zero is used. If expr1b is omitted the length of the
807string minus one is used.
808
809A negative number can be used to measure from the end of the string. -1 is
810the last character, -2 the last but one, etc.
811
812If an index goes out of range for the string characters are omitted. If
813expr1b is smaller than expr1a the result is an empty string.
814
815Examples: >
816 :let c = name[-1:] " last byte of a string
817 :let c = name[-2:-2] " last but one byte of a string
818 :let s = line(".")[4:] " from the fifth byte to the end
819 :let s = s[:-3] " remove last two bytes
820
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000821If expr8 is a List this results in a new List with the items indicated by the
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000822indexes expr1a and expr1b. This works like with a String, as explained just
823above, except that indexes out of range cause an error. Examples: >
824 :let l = mylist[:3] " first four items
825 :let l = mylist[4:4] " List with one item
826 :let l = mylist[:] " shallow copy of a List
827
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000828Using expr8[expr1] or expr8[expr1a : expr1b] on a Funcref results in an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000829
Bram Moolenaard8b02732005-01-14 21:48:43 +0000830
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000831expr8.name entry in a Dictionary *expr-entry*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000832
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000833If expr8 is a Dictionary and it is followed by a dot, then the following name
834will be used as a key in the Dictionary. This is just like: expr8[name].
Bram Moolenaard8b02732005-01-14 21:48:43 +0000835
836The name must consist of alphanumeric characters, just like a variable name,
837but it may start with a number. Curly braces cannot be used.
838
839There must not be white space before or after the dot.
840
841Examples: >
842 :let dict = {"one": 1, 2: "two"}
843 :echo dict.one
844 :echo dict .2
845
846Note that the dot is also used for String concatenation. To avoid confusion
847always put spaces around the dot for String concatenation.
848
849
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000850expr8(expr1, ...) Funcref function call
851
852When expr8 is a |Funcref| type variable, invoke the function it refers to.
853
854
855
856 *expr9*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000857number
858------
859number number constant *expr-number*
860
861Decimal, Hexadecimal (starting with 0x or 0X), or Octal (starting with 0).
862
863
864string *expr-string* *E114*
865------
866"string" string constant *expr-quote*
867
868Note that double quotes are used.
869
870A string constant accepts these special characters:
871\... three-digit octal number (e.g., "\316")
872\.. two-digit octal number (must be followed by non-digit)
873\. one-digit octal number (must be followed by non-digit)
874\x.. byte specified with two hex numbers (e.g., "\x1f")
875\x. byte specified with one hex number (must be followed by non-hex char)
876\X.. same as \x..
877\X. same as \x.
878\u.... character specified with up to 4 hex numbers, stored according to the
879 current value of 'encoding' (e.g., "\u02a4")
880\U.... same as \u....
881\b backspace <BS>
882\e escape <Esc>
883\f formfeed <FF>
884\n newline <NL>
885\r return <CR>
886\t tab <Tab>
887\\ backslash
888\" double quote
889\<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W.
890
891Note that "\000" and "\x00" force the end of the string.
892
893
894literal-string *literal-string* *E115*
895---------------
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000896'string' string constant *expr-'*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000897
898Note that single quotes are used.
899
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000900This string is taken as it is. No backslashes are removed or have a special
Bram Moolenaard8b02732005-01-14 21:48:43 +0000901meaning. The only exception is that two quotes stand for one quote.
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000902
903Single quoted strings are useful for patterns, so that backslashes do not need
904to be doubled. These two commands are equivalent: >
905 if a =~ "\\s*"
906 if a =~ '\s*'
Bram Moolenaar071d4272004-06-13 20:20:40 +0000907
908
909option *expr-option* *E112* *E113*
910------
911&option option value, local value if possible
912&g:option global option value
913&l:option local option value
914
915Examples: >
916 echo "tabstop is " . &tabstop
917 if &insertmode
918
919Any option name can be used here. See |options|. When using the local value
920and there is no buffer-local or window-local value, the global value is used
921anyway.
922
923
924register *expr-register*
925--------
926@r contents of register 'r'
927
928The result is the contents of the named register, as a single string.
929Newlines are inserted where required. To get the contents of the unnamed
930register use @" or @@. The '=' register can not be used here. See
931|registers| for an explanation of the available registers.
932
933
934nesting *expr-nesting* *E110*
935-------
936(expr1) nested expression
937
938
939environment variable *expr-env*
940--------------------
941$VAR environment variable
942
943The String value of any environment variable. When it is not defined, the
944result is an empty string.
945 *expr-env-expand*
946Note that there is a difference between using $VAR directly and using
947expand("$VAR"). Using it directly will only expand environment variables that
948are known inside the current Vim session. Using expand() will first try using
949the environment variables known inside the current Vim session. If that
950fails, a shell will be used to expand the variable. This can be slow, but it
951does expand all variables that the shell knows about. Example: >
952 :echo $version
953 :echo expand("$version")
954The first one probably doesn't echo anything, the second echoes the $version
955variable (if your shell supports it).
956
957
958internal variable *expr-variable*
959-----------------
960variable internal variable
961See below |internal-variables|.
962
963
964function call *expr-function* *E116* *E117* *E118* *E119* *E120*
965-------------
966function(expr1, ...) function call
967See below |functions|.
968
969
970==============================================================================
9713. Internal variable *internal-variables* *E121*
972 *E461*
973An internal variable name can be made up of letters, digits and '_'. But it
974cannot start with a digit. It's also possible to use curly braces, see
975|curly-braces-names|.
976
977An internal variable is created with the ":let" command |:let|.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000978An internal variable is explicitly destroyed with the ":unlet" command
979|:unlet|.
980Using a name that is not an internal variable or refers to a variable that has
981been destroyed results in an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000982
983There are several name spaces for variables. Which one is to be used is
984specified by what is prepended:
985
986 (nothing) In a function: local to a function; otherwise: global
987|buffer-variable| b: Local to the current buffer.
988|window-variable| w: Local to the current window.
989|global-variable| g: Global.
990|local-variable| l: Local to a function.
991|script-variable| s: Local to a |:source|'ed Vim script.
992|function-argument| a: Function argument (only inside a function).
993|vim-variable| v: Global, predefined by Vim.
994
Bram Moolenaar8f999f12005-01-25 22:12:55 +0000995The scope name by itself can be used as a Dictionary. For example, to delete
996all script-local variables: >
997 :for k in keys(s:)
998 : unlet s:[k]
999 :endfor
1000<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001001 *buffer-variable* *b:var*
1002A variable name that is preceded with "b:" is local to the current buffer.
1003Thus you can have several "b:foo" variables, one for each buffer.
1004This kind of variable is deleted when the buffer is wiped out or deleted with
1005|:bdelete|.
1006
1007One local buffer variable is predefined:
1008 *b:changedtick-variable* *changetick*
1009b:changedtick The total number of changes to the current buffer. It is
1010 incremented for each change. An undo command is also a change
1011 in this case. This can be used to perform an action only when
1012 the buffer has changed. Example: >
1013 :if my_changedtick != b:changedtick
1014 : let my_changedtick = b:changedtick
1015 : call My_Update()
1016 :endif
1017<
1018 *window-variable* *w:var*
1019A variable name that is preceded with "w:" is local to the current window. It
1020is deleted when the window is closed.
1021
1022 *global-variable* *g:var*
1023Inside functions global variables are accessed with "g:". Omitting this will
1024access a variable local to a function. But "g:" can also be used in any other
1025place if you like.
1026
1027 *local-variable* *l:var*
1028Inside functions local variables are accessed without prepending anything.
1029But you can also prepend "l:" if you like.
1030
1031 *script-variable* *s:var*
1032In a Vim script variables starting with "s:" can be used. They cannot be
1033accessed from outside of the scripts, thus are local to the script.
1034
1035They can be used in:
1036- commands executed while the script is sourced
1037- functions defined in the script
1038- autocommands defined in the script
1039- functions and autocommands defined in functions and autocommands which were
1040 defined in the script (recursively)
1041- user defined commands defined in the script
1042Thus not in:
1043- other scripts sourced from this one
1044- mappings
1045- etc.
1046
1047script variables can be used to avoid conflicts with global variable names.
1048Take this example:
1049
1050 let s:counter = 0
1051 function MyCounter()
1052 let s:counter = s:counter + 1
1053 echo s:counter
1054 endfunction
1055 command Tick call MyCounter()
1056
1057You can now invoke "Tick" from any script, and the "s:counter" variable in
1058that script will not be changed, only the "s:counter" in the script where
1059"Tick" was defined is used.
1060
1061Another example that does the same: >
1062
1063 let s:counter = 0
1064 command Tick let s:counter = s:counter + 1 | echo s:counter
1065
1066When calling a function and invoking a user-defined command, the context for
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001067script variables is set to the script where the function or command was
Bram Moolenaar071d4272004-06-13 20:20:40 +00001068defined.
1069
1070The script variables are also available when a function is defined inside a
1071function that is defined in a script. Example: >
1072
1073 let s:counter = 0
1074 function StartCounting(incr)
1075 if a:incr
1076 function MyCounter()
1077 let s:counter = s:counter + 1
1078 endfunction
1079 else
1080 function MyCounter()
1081 let s:counter = s:counter - 1
1082 endfunction
1083 endif
1084 endfunction
1085
1086This defines the MyCounter() function either for counting up or counting down
1087when calling StartCounting(). It doesn't matter from where StartCounting() is
1088called, the s:counter variable will be accessible in MyCounter().
1089
1090When the same script is sourced again it will use the same script variables.
1091They will remain valid as long as Vim is running. This can be used to
1092maintain a counter: >
1093
1094 if !exists("s:counter")
1095 let s:counter = 1
1096 echo "script executed for the first time"
1097 else
1098 let s:counter = s:counter + 1
1099 echo "script executed " . s:counter . " times now"
1100 endif
1101
1102Note that this means that filetype plugins don't get a different set of script
1103variables for each buffer. Use local buffer variables instead |b:var|.
1104
1105
1106Predefined Vim variables: *vim-variable* *v:var*
1107
1108 *v:charconvert_from* *charconvert_from-variable*
1109v:charconvert_from
1110 The name of the character encoding of a file to be converted.
1111 Only valid while evaluating the 'charconvert' option.
1112
1113 *v:charconvert_to* *charconvert_to-variable*
1114v:charconvert_to
1115 The name of the character encoding of a file after conversion.
1116 Only valid while evaluating the 'charconvert' option.
1117
1118 *v:cmdarg* *cmdarg-variable*
1119v:cmdarg This variable is used for two purposes:
1120 1. The extra arguments given to a file read/write command.
1121 Currently these are "++enc=" and "++ff=". This variable is
1122 set before an autocommand event for a file read/write
1123 command is triggered. There is a leading space to make it
1124 possible to append this variable directly after the
1125 read/write command. Note: The "+cmd" argument isn't
1126 included here, because it will be executed anyway.
1127 2. When printing a PostScript file with ":hardcopy" this is
1128 the argument for the ":hardcopy" command. This can be used
1129 in 'printexpr'.
1130
1131 *v:cmdbang* *cmdbang-variable*
1132v:cmdbang Set like v:cmdarg for a file read/write command. When a "!"
1133 was used the value is 1, otherwise it is 0. Note that this
1134 can only be used in autocommands. For user commands |<bang>|
1135 can be used.
1136
1137 *v:count* *count-variable*
1138v:count The count given for the last Normal mode command. Can be used
1139 to get the count before a mapping. Read-only. Example: >
1140 :map _x :<C-U>echo "the count is " . v:count<CR>
1141< Note: The <C-U> is required to remove the line range that you
1142 get when typing ':' after a count.
1143 "count" also works, for backwards compatibility.
1144
1145 *v:count1* *count1-variable*
1146v:count1 Just like "v:count", but defaults to one when no count is
1147 used.
1148
1149 *v:ctype* *ctype-variable*
1150v:ctype The current locale setting for characters of the runtime
1151 environment. This allows Vim scripts to be aware of the
1152 current locale encoding. Technical: it's the value of
1153 LC_CTYPE. When not using a locale the value is "C".
1154 This variable can not be set directly, use the |:language|
1155 command.
1156 See |multi-lang|.
1157
1158 *v:dying* *dying-variable*
1159v:dying Normally zero. When a deadly signal is caught it's set to
1160 one. When multiple signals are caught the number increases.
1161 Can be used in an autocommand to check if Vim didn't
1162 terminate normally. {only works on Unix}
1163 Example: >
1164 :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
1165<
1166 *v:errmsg* *errmsg-variable*
1167v:errmsg Last given error message. It's allowed to set this variable.
1168 Example: >
1169 :let v:errmsg = ""
1170 :silent! next
1171 :if v:errmsg != ""
1172 : ... handle error
1173< "errmsg" also works, for backwards compatibility.
1174
1175 *v:exception* *exception-variable*
1176v:exception The value of the exception most recently caught and not
1177 finished. See also |v:throwpoint| and |throw-variables|.
1178 Example: >
1179 :try
1180 : throw "oops"
1181 :catch /.*/
1182 : echo "caught" v:exception
1183 :endtry
1184< Output: "caught oops".
1185
1186 *v:fname_in* *fname_in-variable*
1187v:fname_in The name of the input file. Only valid while evaluating:
1188 option used for ~
1189 'charconvert' file to be converted
1190 'diffexpr' original file
1191 'patchexpr' original file
1192 'printexpr' file to be printed
1193
1194 *v:fname_out* *fname_out-variable*
1195v:fname_out The name of the output file. Only valid while
1196 evaluating:
1197 option used for ~
1198 'charconvert' resulting converted file (*)
1199 'diffexpr' output of diff
1200 'patchexpr' resulting patched file
1201 (*) When doing conversion for a write command (e.g., ":w
1202 file") it will be equal to v:fname_in. When doing conversion
1203 for a read command (e.g., ":e file") it will be a temporary
1204 file and different from v:fname_in.
1205
1206 *v:fname_new* *fname_new-variable*
1207v:fname_new The name of the new version of the file. Only valid while
1208 evaluating 'diffexpr'.
1209
1210 *v:fname_diff* *fname_diff-variable*
1211v:fname_diff The name of the diff (patch) file. Only valid while
1212 evaluating 'patchexpr'.
1213
1214 *v:folddashes* *folddashes-variable*
1215v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed
1216 fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001217 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001218
1219 *v:foldlevel* *foldlevel-variable*
1220v:foldlevel Used for 'foldtext': foldlevel of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001221 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001222
1223 *v:foldend* *foldend-variable*
1224v:foldend Used for 'foldtext': last line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001225 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001226
1227 *v:foldstart* *foldstart-variable*
1228v:foldstart Used for 'foldtext': first line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001229 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001230
Bram Moolenaar843ee412004-06-30 16:16:41 +00001231 *v:insertmode* *insertmode-variable*
1232v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand
1233 events. Values:
1234 i Insert mode
1235 r Replace mode
1236 v Virtual Replace mode
1237
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001238 *v:key* *key-variable*
1239v:key Key of the current item of a Dictionary. Only valid while
1240 evaluating the expression used with |map()| and |filter()|.
1241 Read-only.
1242
Bram Moolenaar071d4272004-06-13 20:20:40 +00001243 *v:lang* *lang-variable*
1244v:lang The current locale setting for messages of the runtime
1245 environment. This allows Vim scripts to be aware of the
1246 current language. Technical: it's the value of LC_MESSAGES.
1247 The value is system dependent.
1248 This variable can not be set directly, use the |:language|
1249 command.
1250 It can be different from |v:ctype| when messages are desired
1251 in a different language than what is used for character
1252 encoding. See |multi-lang|.
1253
1254 *v:lc_time* *lc_time-variable*
1255v:lc_time The current locale setting for time messages of the runtime
1256 environment. This allows Vim scripts to be aware of the
1257 current language. Technical: it's the value of LC_TIME.
1258 This variable can not be set directly, use the |:language|
1259 command. See |multi-lang|.
1260
1261 *v:lnum* *lnum-variable*
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001262v:lnum Line number for the 'foldexpr' |fold-expr| and 'indentexpr'
1263 expressions. Only valid while one of these expressions is
1264 being evaluated. Read-only when in the |sandbox|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001265
1266 *v:prevcount* *prevcount-variable*
1267v:prevcount The count given for the last but one Normal mode command.
1268 This is the v:count value of the previous command. Useful if
1269 you want to cancel Visual mode and then use the count. >
1270 :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
1271< Read-only.
1272
1273 *v:progname* *progname-variable*
1274v:progname Contains the name (with path removed) with which Vim was
1275 invoked. Allows you to do special initialisations for "view",
1276 "evim" etc., or any other name you might symlink to Vim.
1277 Read-only.
1278
1279 *v:register* *register-variable*
1280v:register The name of the register supplied to the last normal mode
1281 command. Empty if none were supplied. |getreg()| |setreg()|
1282
1283 *v:servername* *servername-variable*
1284v:servername The resulting registered |x11-clientserver| name if any.
1285 Read-only.
1286
1287 *v:shell_error* *shell_error-variable*
1288v:shell_error Result of the last shell command. When non-zero, the last
1289 shell command had an error. When zero, there was no problem.
1290 This only works when the shell returns the error code to Vim.
1291 The value -1 is often used when the command could not be
1292 executed. Read-only.
1293 Example: >
1294 :!mv foo bar
1295 :if v:shell_error
1296 : echo 'could not rename "foo" to "bar"!'
1297 :endif
1298< "shell_error" also works, for backwards compatibility.
1299
1300 *v:statusmsg* *statusmsg-variable*
1301v:statusmsg Last given status message. It's allowed to set this variable.
1302
1303 *v:termresponse* *termresponse-variable*
1304v:termresponse The escape sequence returned by the terminal for the |t_RV|
1305 termcap entry. It is set when Vim receives an escape sequence
1306 that starts with ESC [ or CSI and ends in a 'c', with only
1307 digits, ';' and '.' in between.
1308 When this option is set, the TermResponse autocommand event is
1309 fired, so that you can react to the response from the
1310 terminal.
1311 The response from a new xterm is: "<Esc>[ Pp ; Pv ; Pc c". Pp
1312 is the terminal type: 0 for vt100 and 1 for vt220. Pv is the
1313 patch level (since this was introduced in patch 95, it's
1314 always 95 or bigger). Pc is always zero.
1315 {only when compiled with |+termresponse| feature}
1316
1317 *v:this_session* *this_session-variable*
1318v:this_session Full filename of the last loaded or saved session file. See
1319 |:mksession|. It is allowed to set this variable. When no
1320 session file has been saved, this variable is empty.
1321 "this_session" also works, for backwards compatibility.
1322
1323 *v:throwpoint* *throwpoint-variable*
1324v:throwpoint The point where the exception most recently caught and not
1325 finished was thrown. Not set when commands are typed. See
1326 also |v:exception| and |throw-variables|.
1327 Example: >
1328 :try
1329 : throw "oops"
1330 :catch /.*/
1331 : echo "Exception from" v:throwpoint
1332 :endtry
1333< Output: "Exception from test.vim, line 2"
1334
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001335 *v:val* *val-variable*
1336v:val Value of the current item of a List or Dictionary. Only valid
1337 while evaluating the expression used with |map()| and
1338 |filter()|. Read-only.
1339
Bram Moolenaar071d4272004-06-13 20:20:40 +00001340 *v:version* *version-variable*
1341v:version Version number of Vim: Major version number times 100 plus
1342 minor version number. Version 5.0 is 500. Version 5.1 (5.01)
1343 is 501. Read-only. "version" also works, for backwards
1344 compatibility.
1345 Use |has()| to check if a certain patch was included, e.g.: >
1346 if has("patch123")
1347< Note that patch numbers are specific to the version, thus both
1348 version 5.0 and 5.1 may have a patch 123, but these are
1349 completely different.
1350
1351 *v:warningmsg* *warningmsg-variable*
1352v:warningmsg Last given warning message. It's allowed to set this variable.
1353
1354==============================================================================
13554. Builtin Functions *functions*
1356
1357See |function-list| for a list grouped by what the function is used for.
1358
1359(Use CTRL-] on the function name to jump to the full explanation)
1360
1361USAGE RESULT DESCRIPTION ~
1362
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001363add( {list}, {item}) List append {item} to List {list}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001364append( {lnum}, {string}) Number append {string} below line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001365argc() Number number of files in the argument list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001366argidx() Number current index in the argument list
Bram Moolenaar071d4272004-06-13 20:20:40 +00001367argv( {nr}) String {nr} entry of the argument list
1368browse( {save}, {title}, {initdir}, {default})
1369 String put up a file requester
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001370browsedir( {title}, {initdir}) String put up a directory requester
Bram Moolenaar071d4272004-06-13 20:20:40 +00001371bufexists( {expr}) Number TRUE if buffer {expr} exists
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001372buflisted( {expr}) Number TRUE if buffer {expr} is listed
1373bufloaded( {expr}) Number TRUE if buffer {expr} is loaded
Bram Moolenaar071d4272004-06-13 20:20:40 +00001374bufname( {expr}) String Name of the buffer {expr}
1375bufnr( {expr}) Number Number of the buffer {expr}
1376bufwinnr( {expr}) Number window number of buffer {expr}
1377byte2line( {byte}) Number line number at byte count {byte}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001378byteidx( {expr}, {nr}) Number byte index of {nr}'th char in {expr}
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001379call( {func}, {arglist} [, {dict}])
1380 any call {func} with arguments {arglist}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001381char2nr( {expr}) Number ASCII value of first char in {expr}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001382cindent( {lnum}) Number C indent for line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001383col( {expr}) Number column nr of cursor or mark
1384confirm( {msg} [, {choices} [, {default} [, {type}]]])
1385 Number number of choice picked by user
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001386copy( {expr}) any make a shallow copy of {expr}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001387count( {list}, {expr} [, {start} [, {ic}]])
1388 Number count how many {expr} are in {list}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001389cscope_connection( [{num} , {dbpath} [, {prepend}]])
1390 Number checks existence of cscope connection
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001391cursor( {lnum}, {col}) Number position cursor at {lnum}, {col}
1392deepcopy( {expr}) any make a full copy of {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001393delete( {fname}) Number delete file {fname}
1394did_filetype() Number TRUE if FileType autocommand event used
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001395diff_filler( {lnum}) Number diff filler lines about {lnum}
1396diff_hlID( {lnum}, {col}) Number diff highlighting at {lnum}/{col}
Bram Moolenaar13065c42005-01-08 16:08:21 +00001397empty( {expr}) Number TRUE if {expr} is empty
Bram Moolenaar071d4272004-06-13 20:20:40 +00001398escape( {string}, {chars}) String escape {chars} in {string} with '\'
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001399eval( {string}) any evaluate {string} into its value
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001400eventhandler( ) Number TRUE if inside an event handler
Bram Moolenaar071d4272004-06-13 20:20:40 +00001401executable( {expr}) Number 1 if executable {expr} exists
1402exists( {expr}) Number TRUE if {expr} exists
1403expand( {expr}) String expand special keywords in {expr}
1404filereadable( {file}) Number TRUE if {file} is a readable file
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001405filter( {expr}, {string}) List/Dict remove items from {expr} where
1406 {string} is 0
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001407finddir( {name}[, {path}[, {count}]])
1408 String Find directory {name} in {path}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001409findfile( {name}[, {path}[, {count}]])
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001410 String Find file {name} in {path}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001411filewritable( {file}) Number TRUE if {file} is a writable file
1412fnamemodify( {fname}, {mods}) String modify file name
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001413foldclosed( {lnum}) Number first line of fold at {lnum} if closed
1414foldclosedend( {lnum}) Number last line of fold at {lnum} if closed
Bram Moolenaar071d4272004-06-13 20:20:40 +00001415foldlevel( {lnum}) Number fold level at {lnum}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001416foldtext( ) String line displayed for closed fold
Bram Moolenaar071d4272004-06-13 20:20:40 +00001417foreground( ) Number bring the Vim window to the foreground
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001418function( {name}) Funcref reference to function {name}
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001419get( {list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001420get( {dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001421getchar( [expr]) Number get one character from the user
1422getcharmod( ) Number modifiers for the last typed character
Bram Moolenaar071d4272004-06-13 20:20:40 +00001423getbufvar( {expr}, {varname}) variable {varname} in buffer {expr}
1424getcmdline() String return the current command-line
1425getcmdpos() Number return cursor position in command-line
1426getcwd() String the current working directory
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00001427getfperm( {fname}) String file permissions of file {fname}
1428getfsize( {fname}) Number size in bytes of file {fname}
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00001429getfontname( [{name}]) String name of font being used
Bram Moolenaar071d4272004-06-13 20:20:40 +00001430getftime( {fname}) Number last modification time of file
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00001431getftype( {fname}) String description of type of file {fname}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001432getline( {lnum}) String line {lnum} from current buffer
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001433getreg( [{regname}]) String contents of register
1434getregtype( [{regname}]) String type of register
Bram Moolenaar071d4272004-06-13 20:20:40 +00001435getwinposx() Number X coord in pixels of GUI Vim window
1436getwinposy() Number Y coord in pixels of GUI Vim window
1437getwinvar( {nr}, {varname}) variable {varname} in window {nr}
1438glob( {expr}) String expand file wildcards in {expr}
1439globpath( {path}, {expr}) String do glob({expr}) for all dirs in {path}
1440has( {feature}) Number TRUE if feature {feature} supported
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001441has_key( {dict}, {key}) Number TRUE if {dict} has entry {key}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001442hasmapto( {what} [, {mode}]) Number TRUE if mapping to {what} exists
1443histadd( {history},{item}) String add an item to a history
1444histdel( {history} [, {item}]) String remove an item from a history
1445histget( {history} [, {index}]) String get the item {index} from a history
1446histnr( {history}) Number highest index of a history
1447hlexists( {name}) Number TRUE if highlight group {name} exists
1448hlID( {name}) Number syntax ID of highlight group {name}
1449hostname() String name of the machine Vim is running on
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001450iconv( {expr}, {from}, {to}) String convert encoding of {expr}
1451indent( {lnum}) Number indent of line {lnum}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001452index( {list}, {expr} [, {start} [, {ic}]])
1453 Number index in {list} where {expr} appears
Bram Moolenaar071d4272004-06-13 20:20:40 +00001454input( {prompt} [, {text}]) String get input from the user
1455inputdialog( {p} [, {t} [, {c}]]) String like input() but in a GUI dialog
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001456inputrestore() Number restore typeahead
1457inputsave() Number save and clear typeahead
Bram Moolenaar071d4272004-06-13 20:20:40 +00001458inputsecret( {prompt} [, {text}]) String like input() but hiding the text
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001459insert( {list}, {item} [, {idx}]) List insert {item} in {list} [before {idx}]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001460isdirectory( {directory}) Number TRUE if {directory} is a directory
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001461join( {list} [, {sep}]) String join {list} items into one String
Bram Moolenaard8b02732005-01-14 21:48:43 +00001462keys( {dict}) List List of keys in {dict}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001463len( {expr}) Number the length of {expr}
1464libcall( {lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001465libcallnr( {lib}, {func}, {arg}) Number idem, but return a Number
1466line( {expr}) Number line nr of cursor, last line or mark
1467line2byte( {lnum}) Number byte count of line {lnum}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001468lispindent( {lnum}) Number Lisp indent for line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001469localtime() Number current time
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001470map( {expr}, {string}) List/Dict change each item in {expr} to {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001471maparg( {name}[, {mode}]) String rhs of mapping {name} in mode {mode}
1472mapcheck( {name}[, {mode}]) String check for mappings matching {name}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001473match( {expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00001474 Number position where {pat} matches in {expr}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001475matchend( {expr}, {pat}[, {start}[, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00001476 Number position where {pat} ends in {expr}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00001477matchstr( {expr}, {pat}[, {start}[, {count}]])
1478 String {count}'th match of {pat} in {expr}
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001479max({list}) Number maximum value of items in {list}
1480min({list}) Number minumum value of items in {list}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001481mode() String current editing mode
Bram Moolenaar071d4272004-06-13 20:20:40 +00001482nextnonblank( {lnum}) Number line nr of non-blank line >= {lnum}
1483nr2char( {expr}) String single char with ASCII value {expr}
1484prevnonblank( {lnum}) Number line nr of non-blank line <= {lnum}
Bram Moolenaard8b02732005-01-14 21:48:43 +00001485range( {expr} [, {max} [, {stride}]])
1486 List items from {expr} to {max}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001487remote_expr( {server}, {string} [, {idvar}])
1488 String send expression
1489remote_foreground( {server}) Number bring Vim server to the foreground
1490remote_peek( {serverid} [, {retvar}])
1491 Number check for reply string
1492remote_read( {serverid}) String read reply string
1493remote_send( {server}, {string} [, {idvar}])
1494 String send key sequence
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001495remove( {list}, {idx} [, {end}]) any remove items {idx}-{end} from {list}
Bram Moolenaard8b02732005-01-14 21:48:43 +00001496remove( {dict}, {key}) any remove entry {key} from {dict}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001497rename( {from}, {to}) Number rename (move) file from {from} to {to}
1498repeat( {expr}, {count}) String repeat {expr} {count} times
1499resolve( {filename}) String get filename a shortcut points to
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001500reverse( {list}) List reverse {list} in-place
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001501search( {pattern} [, {flags}]) Number search for {pattern}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001502searchpair( {start}, {middle}, {end} [, {flags} [, {skip}]])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001503 Number search for other end of start/end pair
Bram Moolenaar071d4272004-06-13 20:20:40 +00001504server2client( {clientid}, {string})
1505 Number send reply string
1506serverlist() String get a list of available servers
1507setbufvar( {expr}, {varname}, {val}) set {varname} in buffer {expr} to {val}
1508setcmdpos( {pos}) Number set cursor position in command-line
1509setline( {lnum}, {line}) Number set line {lnum} to {line}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001510setreg( {n}, {v}[, {opt}]) Number set register to value and type
Bram Moolenaar071d4272004-06-13 20:20:40 +00001511setwinvar( {nr}, {varname}, {val}) set {varname} in window {nr} to {val}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001512simplify( {filename}) String simplify filename as much as possible
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001513sort( {list} [, {func}]) List sort {list}, using {func} to compare
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001514split( {expr} [, {pat}]) List make List from {pat} separated {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001515strftime( {format}[, {time}]) String time in specified format
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001516stridx( {haystack}, {needle}[, {start}])
1517 Number index of {needle} in {haystack}
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001518string( {expr}) String String representation of {expr} value
Bram Moolenaar071d4272004-06-13 20:20:40 +00001519strlen( {expr}) Number length of the String {expr}
1520strpart( {src}, {start}[, {len}])
1521 String {len} characters of {src} at {start}
1522strridx( {haystack}, {needle}) Number last index of {needle} in {haystack}
1523strtrans( {expr}) String translate string to make it printable
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001524submatch( {nr}) String specific match in ":substitute"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001525substitute( {expr}, {pat}, {sub}, {flags})
1526 String all {pat} in {expr} replaced with {sub}
Bram Moolenaar47136d72004-10-12 20:02:24 +00001527synID( {lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001528synIDattr( {synID}, {what} [, {mode}])
1529 String attribute {what} of syntax ID {synID}
1530synIDtrans( {synID}) Number translated syntax ID of {synID}
Bram Moolenaarc0197e22004-09-13 20:26:32 +00001531system( {expr} [, {input}]) String output of shell command/filter {expr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001532tempname() String name for a temporary file
1533tolower( {expr}) String the String {expr} switched to lowercase
1534toupper( {expr}) String the String {expr} switched to uppercase
Bram Moolenaar8299df92004-07-10 09:47:34 +00001535tr( {src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
1536 to chars in {tostr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001537type( {name}) Number type of variable {name}
1538virtcol( {expr}) Number screen column of cursor or mark
1539visualmode( [expr]) String last visual mode used
1540winbufnr( {nr}) Number buffer number of window {nr}
1541wincol() Number window column of the cursor
1542winheight( {nr}) Number height of window {nr}
1543winline() Number window line of the cursor
1544winnr() Number number of current window
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001545winrestcmd() String returns command to restore window sizes
Bram Moolenaar071d4272004-06-13 20:20:40 +00001546winwidth( {nr}) Number width of window {nr}
1547
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001548add({list}, {expr}) *add()*
1549 Append the item {expr} to List {list}. Returns the resulting
1550 List. Examples: >
1551 :let alist = add([1, 2, 3], item)
1552 :call add(mylist, "woodstock")
1553< Note that when {expr} is a List it is appended as a single
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001554 item. Use |extend()| to concatenate Lists.
Bram Moolenaar13065c42005-01-08 16:08:21 +00001555 Use |insert()| to add an item at another position.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001556
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001557
1558append({lnum}, {expr}) *append()*
1559 When {expr} is a List: Append each item of the list as a text
1560 line below line {lnum} in the current buffer.
1561 Otherwise append the text line {expr} below line {lnum} in the
1562 current buffer.
1563 {lnum} can be zero, to insert a line before the first one.
1564 Returns 1 for failure ({lnum} out of range or out of memory),
1565 0 for success. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001566 :let failed = append(line('$'), "# THE END")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001567 :let failed = append(0, ["Chapter 1", "the beginning"])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001568<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001569 *argc()*
1570argc() The result is the number of files in the argument list of the
1571 current window. See |arglist|.
1572
1573 *argidx()*
1574argidx() The result is the current index in the argument list. 0 is
1575 the first file. argc() - 1 is the last one. See |arglist|.
1576
1577 *argv()*
1578argv({nr}) The result is the {nr}th file in the argument list of the
1579 current window. See |arglist|. "argv(0)" is the first one.
1580 Example: >
1581 :let i = 0
1582 :while i < argc()
1583 : let f = escape(argv(i), '. ')
1584 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>'
1585 : let i = i + 1
1586 :endwhile
1587<
1588 *browse()*
1589browse({save}, {title}, {initdir}, {default})
1590 Put up a file requester. This only works when "has("browse")"
1591 returns non-zero (only in some GUI versions).
1592 The input fields are:
1593 {save} when non-zero, select file to write
1594 {title} title for the requester
1595 {initdir} directory to start browsing in
1596 {default} default file name
1597 When the "Cancel" button is hit, something went wrong, or
1598 browsing is not possible, an empty string is returned.
1599
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001600 *browsedir()*
1601browsedir({title}, {initdir})
1602 Put up a directory requester. This only works when
1603 "has("browse")" returns non-zero (only in some GUI versions).
1604 On systems where a directory browser is not supported a file
1605 browser is used. In that case: select a file in the directory
1606 to be used.
1607 The input fields are:
1608 {title} title for the requester
1609 {initdir} directory to start browsing in
1610 When the "Cancel" button is hit, something went wrong, or
1611 browsing is not possible, an empty string is returned.
1612
Bram Moolenaar071d4272004-06-13 20:20:40 +00001613bufexists({expr}) *bufexists()*
1614 The result is a Number, which is non-zero if a buffer called
1615 {expr} exists.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001616 If the {expr} argument is a number, buffer numbers are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001617 If the {expr} argument is a string it must match a buffer name
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001618 exactly. The name can be:
1619 - Relative to the current directory.
1620 - A full path.
1621 - The name of a buffer with 'filetype' set to "nofile".
1622 - A URL name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001623 Unlisted buffers will be found.
1624 Note that help files are listed by their short name in the
1625 output of |:buffers|, but bufexists() requires using their
1626 long name to be able to find them.
1627 Use "bufexists(0)" to test for the existence of an alternate
1628 file name.
1629 *buffer_exists()*
1630 Obsolete name: buffer_exists().
1631
1632buflisted({expr}) *buflisted()*
1633 The result is a Number, which is non-zero if a buffer called
1634 {expr} exists and is listed (has the 'buflisted' option set).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001635 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001636
1637bufloaded({expr}) *bufloaded()*
1638 The result is a Number, which is non-zero if a buffer called
1639 {expr} exists and is loaded (shown in a window or hidden).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001640 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001641
1642bufname({expr}) *bufname()*
1643 The result is the name of a buffer, as it is displayed by the
1644 ":ls" command.
1645 If {expr} is a Number, that buffer number's name is given.
1646 Number zero is the alternate buffer for the current window.
1647 If {expr} is a String, it is used as a |file-pattern| to match
1648 with the buffer names. This is always done like 'magic' is
1649 set and 'cpoptions' is empty. When there is more than one
1650 match an empty string is returned.
1651 "" or "%" can be used for the current buffer, "#" for the
1652 alternate buffer.
1653 A full match is preferred, otherwise a match at the start, end
1654 or middle of the buffer name is accepted.
1655 Listed buffers are found first. If there is a single match
1656 with a listed buffer, that one is returned. Next unlisted
1657 buffers are searched for.
1658 If the {expr} is a String, but you want to use it as a buffer
1659 number, force it to be a Number by adding zero to it: >
1660 :echo bufname("3" + 0)
1661< If the buffer doesn't exist, or doesn't have a name, an empty
1662 string is returned. >
1663 bufname("#") alternate buffer name
1664 bufname(3) name of buffer 3
1665 bufname("%") name of current buffer
1666 bufname("file2") name of buffer where "file2" matches.
1667< *buffer_name()*
1668 Obsolete name: buffer_name().
1669
1670 *bufnr()*
1671bufnr({expr}) The result is the number of a buffer, as it is displayed by
1672 the ":ls" command. For the use of {expr}, see |bufname()|
1673 above. If the buffer doesn't exist, -1 is returned.
1674 bufnr("$") is the last buffer: >
1675 :let last_buffer = bufnr("$")
1676< The result is a Number, which is the highest buffer number
1677 of existing buffers. Note that not all buffers with a smaller
1678 number necessarily exist, because ":bwipeout" may have removed
1679 them. Use bufexists() to test for the existence of a buffer.
1680 *buffer_number()*
1681 Obsolete name: buffer_number().
1682 *last_buffer_nr()*
1683 Obsolete name for bufnr("$"): last_buffer_nr().
1684
1685bufwinnr({expr}) *bufwinnr()*
1686 The result is a Number, which is the number of the first
1687 window associated with buffer {expr}. For the use of {expr},
1688 see |bufname()| above. If buffer {expr} doesn't exist or
1689 there is no such window, -1 is returned. Example: >
1690
1691 echo "A window containing buffer 1 is " . (bufwinnr(1))
1692
1693< The number can be used with |CTRL-W_w| and ":wincmd w"
1694 |:wincmd|.
1695
1696
1697byte2line({byte}) *byte2line()*
1698 Return the line number that contains the character at byte
1699 count {byte} in the current buffer. This includes the
1700 end-of-line character, depending on the 'fileformat' option
1701 for the current buffer. The first character has byte count
1702 one.
1703 Also see |line2byte()|, |go| and |:goto|.
1704 {not available when compiled without the |+byte_offset|
1705 feature}
1706
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00001707byteidx({expr}, {nr}) *byteidx()*
1708 Return byte index of the {nr}'th character in the string
1709 {expr}. Use zero for the first character, it returns zero.
1710 This function is only useful when there are multibyte
1711 characters, otherwise the returned value is equal to {nr}.
1712 Composing characters are counted as a separate character.
1713 Example : >
1714 echo matchstr(str, ".", byteidx(str, 3))
1715< will display the fourth character. Another way to do the
1716 same: >
1717 let s = strpart(str, byteidx(str, 3))
1718 echo strpart(s, 0, byteidx(s, 1))
1719< If there are less than {nr} characters -1 is returned.
1720 If there are exactly {nr} characters the length of the string
1721 is returned.
1722
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001723call({func}, {arglist} [, {dict}]) *call()* *E699*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001724 Call function {func} with the items in List {arglist} as
1725 arguments.
1726 {func} can either be a Funcref or the name of a function.
1727 a:firstline and a:lastline are set to the cursor line.
1728 Returns the return value of the called function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001729 {dict} is for functions with the "dict" attribute. It will be
1730 used to set the local variable "self". |Dictionary-function|
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001731
Bram Moolenaar071d4272004-06-13 20:20:40 +00001732char2nr({expr}) *char2nr()*
1733 Return number value of the first char in {expr}. Examples: >
1734 char2nr(" ") returns 32
1735 char2nr("ABC") returns 65
1736< The current 'encoding' is used. Example for "utf-8": >
1737 char2nr("á") returns 225
1738 char2nr("á"[0]) returns 195
1739
1740cindent({lnum}) *cindent()*
1741 Get the amount of indent for line {lnum} according the C
1742 indenting rules, as with 'cindent'.
1743 The indent is counted in spaces, the value of 'tabstop' is
1744 relevant. {lnum} is used just like in |getline()|.
1745 When {lnum} is invalid or Vim was not compiled the |+cindent|
1746 feature, -1 is returned.
1747
1748 *col()*
Bram Moolenaarc0197e22004-09-13 20:26:32 +00001749col({expr}) The result is a Number, which is the byte index of the column
Bram Moolenaar071d4272004-06-13 20:20:40 +00001750 position given with {expr}. The accepted positions are:
1751 . the cursor position
1752 $ the end of the cursor line (the result is the
1753 number of characters in the cursor line plus one)
1754 'x position of mark x (if the mark is not set, 0 is
1755 returned)
1756 For the screen column position use |virtcol()|.
1757 Note that only marks in the current file can be used.
1758 Examples: >
1759 col(".") column of cursor
1760 col("$") length of cursor line plus one
1761 col("'t") column of mark t
1762 col("'" . markname) column of mark markname
1763< The first column is 1. 0 is returned for an error.
1764 For the cursor position, when 'virtualedit' is active, the
1765 column is one higher if the cursor is after the end of the
1766 line. This can be used to obtain the column in Insert mode: >
1767 :imap <F2> <C-O>:let save_ve = &ve<CR>
1768 \<C-O>:set ve=all<CR>
1769 \<C-O>:echo col(".") . "\n" <Bar>
1770 \let &ve = save_ve<CR>
1771<
1772 *confirm()*
1773confirm({msg} [, {choices} [, {default} [, {type}]]])
1774 Confirm() offers the user a dialog, from which a choice can be
1775 made. It returns the number of the choice. For the first
1776 choice this is 1.
1777 Note: confirm() is only supported when compiled with dialog
1778 support, see |+dialog_con| and |+dialog_gui|.
1779 {msg} is displayed in a |dialog| with {choices} as the
1780 alternatives. When {choices} is missing or empty, "&OK" is
1781 used (and translated).
1782 {msg} is a String, use '\n' to include a newline. Only on
1783 some systems the string is wrapped when it doesn't fit.
1784 {choices} is a String, with the individual choices separated
1785 by '\n', e.g. >
1786 confirm("Save changes?", "&Yes\n&No\n&Cancel")
1787< The letter after the '&' is the shortcut key for that choice.
1788 Thus you can type 'c' to select "Cancel". The shortcut does
1789 not need to be the first letter: >
1790 confirm("file has been modified", "&Save\nSave &All")
1791< For the console, the first letter of each choice is used as
1792 the default shortcut key.
1793 The optional {default} argument is the number of the choice
1794 that is made if the user hits <CR>. Use 1 to make the first
1795 choice the default one. Use 0 to not set a default. If
1796 {default} is omitted, 1 is used.
1797 The optional {type} argument gives the type of dialog. This
1798 is only used for the icon of the Win32 GUI. It can be one of
1799 these values: "Error", "Question", "Info", "Warning" or
1800 "Generic". Only the first character is relevant. When {type}
1801 is omitted, "Generic" is used.
1802 If the user aborts the dialog by pressing <Esc>, CTRL-C,
1803 or another valid interrupt key, confirm() returns 0.
1804
1805 An example: >
1806 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2)
1807 :if choice == 0
1808 : echo "make up your mind!"
1809 :elseif choice == 3
1810 : echo "tasteful"
1811 :else
1812 : echo "I prefer bananas myself."
1813 :endif
1814< In a GUI dialog, buttons are used. The layout of the buttons
1815 depends on the 'v' flag in 'guioptions'. If it is included,
1816 the buttons are always put vertically. Otherwise, confirm()
1817 tries to put the buttons in one horizontal line. If they
1818 don't fit, a vertical layout is used anyway. For some systems
1819 the horizontal layout is always used.
1820
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001821 *copy()*
1822copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
1823 different from using {expr} directly.
1824 When {expr} is a List a shallow copy is created. This means
1825 that the original List can be changed without changing the
1826 copy, and vise versa. But the items are identical, thus
1827 changing an item changes the contents of both Lists. Also see
1828 |deepcopy()|.
1829
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001830count({comp}, {expr} [, {ic} [, {start}]]) *count()*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001831 Return the number of times an item with value {expr} appears
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001832 in List or Dictionary {comp}.
1833 If {start} is given then start with the item with this index.
1834 {start} can only be used with a List.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001835 When {ic} is given and it's non-zero then case is ignored.
1836
1837
Bram Moolenaar071d4272004-06-13 20:20:40 +00001838 *cscope_connection()*
1839cscope_connection([{num} , {dbpath} [, {prepend}]])
1840 Checks for the existence of a |cscope| connection. If no
1841 parameters are specified, then the function returns:
1842 0, if cscope was not available (not compiled in), or
1843 if there are no cscope connections;
1844 1, if there is at least one cscope connection.
1845
1846 If parameters are specified, then the value of {num}
1847 determines how existence of a cscope connection is checked:
1848
1849 {num} Description of existence check
1850 ----- ------------------------------
1851 0 Same as no parameters (e.g., "cscope_connection()").
1852 1 Ignore {prepend}, and use partial string matches for
1853 {dbpath}.
1854 2 Ignore {prepend}, and use exact string matches for
1855 {dbpath}.
1856 3 Use {prepend}, use partial string matches for both
1857 {dbpath} and {prepend}.
1858 4 Use {prepend}, use exact string matches for both
1859 {dbpath} and {prepend}.
1860
1861 Note: All string comparisons are case sensitive!
1862
1863 Examples. Suppose we had the following (from ":cs show"): >
1864
1865 # pid database name prepend path
1866 0 27664 cscope.out /usr/local
1867<
1868 Invocation Return Val ~
1869 ---------- ---------- >
1870 cscope_connection() 1
1871 cscope_connection(1, "out") 1
1872 cscope_connection(2, "out") 0
1873 cscope_connection(3, "out") 0
1874 cscope_connection(3, "out", "local") 1
1875 cscope_connection(4, "out") 0
1876 cscope_connection(4, "out", "local") 0
1877 cscope_connection(4, "cscope.out", "/usr/local") 1
1878<
1879cursor({lnum}, {col}) *cursor()*
1880 Positions the cursor at the column {col} in the line {lnum}.
1881 Does not change the jumplist.
1882 If {lnum} is greater than the number of lines in the buffer,
1883 the cursor will be positioned at the last line in the buffer.
1884 If {lnum} is zero, the cursor will stay in the current line.
1885 If {col} is greater than the number of characters in the line,
1886 the cursor will be positioned at the last character in the
1887 line.
1888 If {col} is zero, the cursor will stay in the current column.
1889
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001890
Bram Moolenaar13065c42005-01-08 16:08:21 +00001891deepcopy({expr}) *deepcopy()* *E698*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001892 Make a copy of {expr}. For Numbers and Strings this isn't
1893 different from using {expr} directly.
1894 When {expr} is a List a full copy is created. This means
1895 that the original List can be changed without changing the
1896 copy, and vise versa. When an item is a List, a copy for it
1897 is made, recursively. Thus changing an item in the copy does
1898 not change the contents of the original List.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00001899 *E724*
1900 Nesting is possible up to 100 levels. When there is an item
1901 that refers back to a higher level making a deep copy will
1902 fail.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001903 Also see |copy()|.
1904
1905delete({fname}) *delete()*
1906 Deletes the file by the name {fname}. The result is a Number,
Bram Moolenaar071d4272004-06-13 20:20:40 +00001907 which is 0 if the file was deleted successfully, and non-zero
1908 when the deletion failed.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001909 Use |remove()| to delete an item from a List.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001910
1911 *did_filetype()*
1912did_filetype() Returns non-zero when autocommands are being executed and the
1913 FileType event has been triggered at least once. Can be used
1914 to avoid triggering the FileType event again in the scripts
1915 that detect the file type. |FileType|
1916 When editing another file, the counter is reset, thus this
1917 really checks if the FileType event has been triggered for the
1918 current buffer. This allows an autocommand that starts
1919 editing another buffer to set 'filetype' and load a syntax
1920 file.
1921
Bram Moolenaar47136d72004-10-12 20:02:24 +00001922diff_filler({lnum}) *diff_filler()*
1923 Returns the number of filler lines above line {lnum}.
1924 These are the lines that were inserted at this point in
1925 another diff'ed window. These filler lines are shown in the
1926 display but don't exist in the buffer.
1927 {lnum} is used like with |getline()|. Thus "." is the current
1928 line, "'m" mark m, etc.
1929 Returns 0 if the current window is not in diff mode.
1930
1931diff_hlID({lnum}, {col}) *diff_hlID()*
1932 Returns the highlight ID for diff mode at line {lnum} column
1933 {col} (byte index). When the current line does not have a
1934 diff change zero is returned.
1935 {lnum} is used like with |getline()|. Thus "." is the current
1936 line, "'m" mark m, etc.
1937 {col} is 1 for the leftmost column, {lnum} is 1 for the first
1938 line.
1939 The highlight ID can be used with |synIDattr()| to obtain
1940 syntax information about the highlighting.
1941
Bram Moolenaar13065c42005-01-08 16:08:21 +00001942empty({expr}) *empty()*
1943 Return the Number 1 if {expr} is empty, zero otherwise.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001944 A List or Dictionary is empty when it does not have any items.
Bram Moolenaar13065c42005-01-08 16:08:21 +00001945 A Number is empty when its value is zero.
1946 For a long List this is much faster then comparing the length
1947 with zero.
1948
Bram Moolenaar071d4272004-06-13 20:20:40 +00001949escape({string}, {chars}) *escape()*
1950 Escape the characters in {chars} that occur in {string} with a
1951 backslash. Example: >
1952 :echo escape('c:\program files\vim', ' \')
1953< results in: >
1954 c:\\program\ files\\vim
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00001955
1956< *eval()*
1957eval({string}) Evaluate {string} and return the result. Especially useful to
1958 turn the result of |string()| back into the original value.
1959 This works for Numbers, Strings and composites of them.
1960 Also works for Funcrefs that refer to existing functions.
1961
Bram Moolenaar071d4272004-06-13 20:20:40 +00001962eventhandler() *eventhandler()*
1963 Returns 1 when inside an event handler. That is that Vim got
1964 interrupted while waiting for the user to type a character,
1965 e.g., when dropping a file on Vim. This means interactive
1966 commands cannot be used. Otherwise zero is returned.
1967
1968executable({expr}) *executable()*
1969 This function checks if an executable with the name {expr}
1970 exists. {expr} must be the name of the program without any
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00001971 arguments.
1972 executable() uses the value of $PATH and/or the normal
1973 searchpath for programs. *PATHEXT*
1974 On MS-DOS and MS-Windows the ".exe", ".bat", etc. can
1975 optionally be included. Then the extensions in $PATHEXT are
1976 tried. Thus if "foo.exe" does not exist, "foo.exe.bat" can be
1977 found. If $PATHEXT is not set then ".exe;.com;.bat;.cmd" is
1978 used. A dot by itself can be used in $PATHEXT to try using
1979 the name without an extension. When 'shell' looks like a
1980 Unix shell, then the name is also tried without adding an
1981 extension.
1982 On MS-DOS and MS-Windows it only checks if the file exists and
1983 is not a directory, not if it's really executable.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001984 The result is a Number:
1985 1 exists
1986 0 does not exist
1987 -1 not implemented on this system
1988
1989 *exists()*
1990exists({expr}) The result is a Number, which is non-zero if {expr} is
1991 defined, zero otherwise. The {expr} argument is a string,
1992 which contains one of these:
1993 &option-name Vim option (only checks if it exists,
1994 not if it really works)
1995 +option-name Vim option that works.
1996 $ENVNAME environment variable (could also be
1997 done by comparing with an empty
1998 string)
1999 *funcname built-in function (see |functions|)
2000 or user defined function (see
2001 |user-functions|).
2002 varname internal variable (see
2003 |internal-variables|). Does not work
2004 for |curly-braces-names|.
2005 :cmdname Ex command: built-in command, user
2006 command or command modifier |:command|.
2007 Returns:
2008 1 for match with start of a command
2009 2 full match with a command
2010 3 matches several user commands
2011 To check for a supported command
2012 always check the return value to be 2.
2013 #event autocommand defined for this event
2014 #event#pattern autocommand defined for this event and
2015 pattern (the pattern is taken
2016 literally and compared to the
2017 autocommand patterns character by
2018 character)
2019 For checking for a supported feature use |has()|.
2020
2021 Examples: >
2022 exists("&shortname")
2023 exists("$HOSTNAME")
2024 exists("*strftime")
2025 exists("*s:MyFunc")
2026 exists("bufcount")
2027 exists(":Make")
2028 exists("#CursorHold");
2029 exists("#BufReadPre#*.gz")
2030< There must be no space between the symbol (&/$/*/#) and the
2031 name.
2032 Note that the argument must be a string, not the name of the
2033 variable itself! For example: >
2034 exists(bufcount)
2035< This doesn't check for existence of the "bufcount" variable,
2036 but gets the contents of "bufcount", and checks if that
2037 exists.
2038
2039expand({expr} [, {flag}]) *expand()*
2040 Expand wildcards and the following special keywords in {expr}.
2041 The result is a String.
2042
2043 When there are several matches, they are separated by <NL>
2044 characters. [Note: in version 5.0 a space was used, which
2045 caused problems when a file name contains a space]
2046
2047 If the expansion fails, the result is an empty string. A name
2048 for a non-existing file is not included.
2049
2050 When {expr} starts with '%', '#' or '<', the expansion is done
2051 like for the |cmdline-special| variables with their associated
2052 modifiers. Here is a short overview:
2053
2054 % current file name
2055 # alternate file name
2056 #n alternate file name n
2057 <cfile> file name under the cursor
2058 <afile> autocmd file name
2059 <abuf> autocmd buffer number (as a String!)
2060 <amatch> autocmd matched name
2061 <sfile> sourced script file name
2062 <cword> word under the cursor
2063 <cWORD> WORD under the cursor
2064 <client> the {clientid} of the last received
2065 message |server2client()|
2066 Modifiers:
2067 :p expand to full path
2068 :h head (last path component removed)
2069 :t tail (last path component only)
2070 :r root (one extension removed)
2071 :e extension only
2072
2073 Example: >
2074 :let &tags = expand("%:p:h") . "/tags"
2075< Note that when expanding a string that starts with '%', '#' or
2076 '<', any following text is ignored. This does NOT work: >
2077 :let doesntwork = expand("%:h.bak")
2078< Use this: >
2079 :let doeswork = expand("%:h") . ".bak"
2080< Also note that expanding "<cfile>" and others only returns the
2081 referenced file name without further expansion. If "<cfile>"
2082 is "~/.cshrc", you need to do another expand() to have the
2083 "~/" expanded into the path of the home directory: >
2084 :echo expand(expand("<cfile>"))
2085<
2086 There cannot be white space between the variables and the
2087 following modifier. The |fnamemodify()| function can be used
2088 to modify normal file names.
2089
2090 When using '%' or '#', and the current or alternate file name
2091 is not defined, an empty string is used. Using "%:p" in a
2092 buffer with no name, results in the current directory, with a
2093 '/' added.
2094
2095 When {expr} does not start with '%', '#' or '<', it is
2096 expanded like a file name is expanded on the command line.
2097 'suffixes' and 'wildignore' are used, unless the optional
2098 {flag} argument is given and it is non-zero. Names for
2099 non-existing files are included.
2100
2101 Expand() can also be used to expand variables and environment
2102 variables that are only known in a shell. But this can be
2103 slow, because a shell must be started. See |expr-env-expand|.
2104 The expanded variable is still handled like a list of file
2105 names. When an environment variable cannot be expanded, it is
2106 left unchanged. Thus ":echo expand('$FOOBAR')" results in
2107 "$FOOBAR".
2108
2109 See |glob()| for finding existing files. See |system()| for
2110 getting the raw output of an external command.
2111
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002112extend({expr1}, {expr2} [, {expr3}]) *extend()*
2113 {expr1} and {expr2} must be both Lists or both Dictionaries.
2114
2115 If they are Lists: Append {expr2} to {expr1}.
2116 If {expr3} is given insert the items of {expr2} before item
2117 {expr3} in {expr1}. When {expr3} is zero insert before the
2118 first item. When {expr3} is equal to len({expr1}) then
2119 {expr2} is appended.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002120 Examples: >
2121 :echo sort(extend(mylist, [7, 5]))
2122 :call extend(mylist, [2, 3], 1)
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002123< Use |add()| to concatenate one item to a list. To concatenate
2124 two lists into a new list use the + operator: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002125 :let newlist = [1, 2, 3] + [4, 5]
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002126<
2127 If they are Dictionaries:
2128 Add all entries from {expr2} to {expr1}.
2129 If a key exists in both {expr1} and {expr2} then {expr3} is
2130 used to decide what to do:
2131 {expr3} = "keep": keep the value of {expr1}
2132 {expr3} = "force": use the value of {expr2}
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00002133 {expr3} = "error": give an error message *E737*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002134 When {expr3} is omitted then "force" is assumed.
2135
2136 {expr1} is changed when {expr2} is not empty. If necessary
2137 make a copy of {expr1} first.
2138 {expr2} remains unchanged.
2139 Returns {expr1}.
2140
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002141
Bram Moolenaar071d4272004-06-13 20:20:40 +00002142filereadable({file}) *filereadable()*
2143 The result is a Number, which is TRUE when a file with the
2144 name {file} exists, and can be read. If {file} doesn't exist,
2145 or is a directory, the result is FALSE. {file} is any
2146 expression, which is used as a String.
2147 *file_readable()*
2148 Obsolete name: file_readable().
2149
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002150
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002151filter({expr}, {string}) *filter()*
2152 {expr} must be a List or a Dictionary.
2153 For each item in {expr} evaluate {string} and when the result
2154 is zero remove the item from the List or Dictionary.
2155 Inside {string} |v:val| has the value of the current item.
2156 For a Dictionary |v:key| has the key of the current item.
2157 Examples: >
2158 :call filter(mylist, 'v:val !~ "OLD"')
2159< Removes the items where "OLD" appears. >
2160 :call filter(mydict, 'v:key >= 8')
2161< Removes the items with a key below 8. >
2162 :call filter(var, 0)
Bram Moolenaard8b02732005-01-14 21:48:43 +00002163< Removes all the items, thus clears the List or Dictionary.
2164
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002165 Note that {string} is the result of expression and is then
2166 used as an expression again. Often it is good to use a
2167 |literal-string| to avoid having to double backslashes.
2168
2169 The operation is done in-place. If you want a List or
2170 Dictionary to remain unmodified make a copy first: >
Bram Moolenaard8b02732005-01-14 21:48:43 +00002171 :let l = filter(copy(mylist), '& =~ "KEEP"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002172
2173< Returns {expr}, the List or Dictionary that was filtered.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002174
2175
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002176finddir({name}[, {path}[, {count}]]) *finddir()*
2177 Find directory {name} in {path}.
2178 If {path} is omitted or empty then 'path' is used.
2179 If the optional {count} is given, find {count}'s occurrence of
2180 {name} in {path}.
2181 This is quite similar to the ex-command |:find|.
2182 When the found directory is below the current directory a
2183 relative path is returned. Otherwise a full path is returned.
2184 Example: >
2185 :echo findfile("tags.vim", ".;")
2186< Searches from the current directory upwards until it finds
2187 the file "tags.vim".
2188 {only available when compiled with the +file_in_path feature}
2189
2190findfile({name}[, {path}[, {count}]]) *findfile()*
2191 Just like |finddir()|, but find a file instead of a directory.
2192
Bram Moolenaar071d4272004-06-13 20:20:40 +00002193filewritable({file}) *filewritable()*
2194 The result is a Number, which is 1 when a file with the
2195 name {file} exists, and can be written. If {file} doesn't
2196 exist, or is not writable, the result is 0. If (file) is a
2197 directory, and we can write to it, the result is 2.
2198
2199fnamemodify({fname}, {mods}) *fnamemodify()*
2200 Modify file name {fname} according to {mods}. {mods} is a
2201 string of characters like it is used for file names on the
2202 command line. See |filename-modifiers|.
2203 Example: >
2204 :echo fnamemodify("main.c", ":p:h")
2205< results in: >
2206 /home/mool/vim/vim/src
2207< Note: Environment variables and "~" don't work in {fname}, use
2208 |expand()| first then.
2209
2210foldclosed({lnum}) *foldclosed()*
2211 The result is a Number. If the line {lnum} is in a closed
2212 fold, the result is the number of the first line in that fold.
2213 If the line {lnum} is not in a closed fold, -1 is returned.
2214
2215foldclosedend({lnum}) *foldclosedend()*
2216 The result is a Number. If the line {lnum} is in a closed
2217 fold, the result is the number of the last line in that fold.
2218 If the line {lnum} is not in a closed fold, -1 is returned.
2219
2220foldlevel({lnum}) *foldlevel()*
2221 The result is a Number, which is the foldlevel of line {lnum}
2222 in the current buffer. For nested folds the deepest level is
2223 returned. If there is no fold at line {lnum}, zero is
2224 returned. It doesn't matter if the folds are open or closed.
2225 When used while updating folds (from 'foldexpr') -1 is
2226 returned for lines where folds are still to be updated and the
2227 foldlevel is unknown. As a special case the level of the
2228 previous line is usually available.
2229
2230 *foldtext()*
2231foldtext() Returns a String, to be displayed for a closed fold. This is
2232 the default function used for the 'foldtext' option and should
2233 only be called from evaluating 'foldtext'. It uses the
2234 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
2235 The returned string looks like this: >
2236 +-- 45 lines: abcdef
2237< The number of dashes depends on the foldlevel. The "45" is
2238 the number of lines in the fold. "abcdef" is the text in the
2239 first non-blank line of the fold. Leading white space, "//"
2240 or "/*" and the text from the 'foldmarker' and 'commentstring'
2241 options is removed.
2242 {not available when compiled without the |+folding| feature}
2243
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00002244foldtextresult({lnum}) *foldtextresult()*
2245 Returns the text that is displayed for the closed fold at line
2246 {lnum}. Evaluates 'foldtext' in the appropriate context.
2247 When there is no closed fold at {lnum} an empty string is
2248 returned.
2249 {lnum} is used like with |getline()|. Thus "." is the current
2250 line, "'m" mark m, etc.
2251 Useful when exporting folded text, e.g., to HTML.
2252 {not available when compiled without the |+folding| feature}
2253
Bram Moolenaar071d4272004-06-13 20:20:40 +00002254 *foreground()*
2255foreground() Move the Vim window to the foreground. Useful when sent from
2256 a client to a Vim server. |remote_send()|
2257 On Win32 systems this might not work, the OS does not always
2258 allow a window to bring itself to the foreground. Use
2259 |remote_foreground()| instead.
2260 {only in the Win32, Athena, Motif and GTK GUI versions and the
2261 Win32 console version}
2262
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002263
Bram Moolenaar13065c42005-01-08 16:08:21 +00002264function({name}) *function()* *E700*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002265 Return a Funcref variable that refers to function {name}.
2266 {name} can be a user defined function or an internal function.
2267
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002268
2269get({list}, {idx} [, {default}]) *get*
2270 Get item {idx} from List {list}. When this item is not
2271 available return {default}. Return zero when {default} is
2272 omitted.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002273get({dict}, {key} [, {default}])
2274 Get item with key {key} from Dictionary {dict}. When this
2275 item is not available return {default}. Return zero when
2276 {default} is omitted.
2277
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002278
2279getbufvar({expr}, {varname}) *getbufvar()*
2280 The result is the value of option or local buffer variable
2281 {varname} in buffer {expr}. Note that the name without "b:"
2282 must be used.
2283 This also works for a global or local window option, but it
2284 doesn't work for a global or local window variable.
2285 For the use of {expr}, see |bufname()| above.
2286 When the buffer or variable doesn't exist an empty string is
2287 returned, there is no error message.
2288 Examples: >
2289 :let bufmodified = getbufvar(1, "&mod")
2290 :echo "todo myvar = " . getbufvar("todo", "myvar")
2291<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002292getchar([expr]) *getchar()*
2293 Get a single character from the user. If it is an 8-bit
2294 character, the result is a number. Otherwise a String is
2295 returned with the encoded character. For a special key it's a
2296 sequence of bytes starting with 0x80 (decimal: 128).
2297 If [expr] is omitted, wait until a character is available.
2298 If [expr] is 0, only get a character when one is available.
2299 If [expr] is 1, only check if a character is available, it is
2300 not consumed. If a normal character is
2301 available, it is returned, otherwise a
2302 non-zero value is returned.
2303 If a normal character available, it is returned as a Number.
2304 Use nr2char() to convert it to a String.
2305 The returned value is zero if no character is available.
2306 The returned value is a string of characters for special keys
2307 and when a modifier (shift, control, alt) was used.
2308 There is no prompt, you will somehow have to make clear to the
2309 user that a character has to be typed.
2310 There is no mapping for the character.
2311 Key codes are replaced, thus when the user presses the <Del>
2312 key you get the code for the <Del> key, not the raw character
2313 sequence. Examples: >
2314 getchar() == "\<Del>"
2315 getchar() == "\<S-Left>"
2316< This example redefines "f" to ignore case: >
2317 :nmap f :call FindChar()<CR>
2318 :function FindChar()
2319 : let c = nr2char(getchar())
2320 : while col('.') < col('$') - 1
2321 : normal l
2322 : if getline('.')[col('.') - 1] ==? c
2323 : break
2324 : endif
2325 : endwhile
2326 :endfunction
2327
2328getcharmod() *getcharmod()*
2329 The result is a Number which is the state of the modifiers for
2330 the last obtained character with getchar() or in another way.
2331 These values are added together:
2332 2 shift
2333 4 control
2334 8 alt (meta)
2335 16 mouse double click
2336 32 mouse triple click
2337 64 mouse quadruple click
2338 128 Macintosh only: command
2339 Only the modifiers that have not been included in the
2340 character itself are obtained. Thus Shift-a results in "A"
2341 with no modifier.
2342
Bram Moolenaar071d4272004-06-13 20:20:40 +00002343getcmdline() *getcmdline()*
2344 Return the current command-line. Only works when the command
2345 line is being edited, thus requires use of |c_CTRL-\_e| or
2346 |c_CTRL-R_=|.
2347 Example: >
2348 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
2349< Also see |getcmdpos()| and |setcmdpos()|.
2350
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002351getcmdpos() *getcmdpos()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002352 Return the position of the cursor in the command line as a
2353 byte count. The first column is 1.
2354 Only works when editing the command line, thus requires use of
2355 |c_CTRL-\_e| or |c_CTRL-R_=|. Returns 0 otherwise.
2356 Also see |setcmdpos()| and |getcmdline()|.
2357
2358 *getcwd()*
2359getcwd() The result is a String, which is the name of the current
2360 working directory.
2361
2362getfsize({fname}) *getfsize()*
2363 The result is a Number, which is the size in bytes of the
2364 given file {fname}.
2365 If {fname} is a directory, 0 is returned.
2366 If the file {fname} can't be found, -1 is returned.
2367
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00002368getfontname([{name}]) *getfontname()*
2369 Without an argument returns the name of the normal font being
2370 used. Like what is used for the Normal highlight group
2371 |hl-Normal|.
2372 With an argument a check is done whether {name} is a valid
2373 font name. If not then an empty string is returned.
2374 Otherwise the actual font name is returned, or {name} if the
2375 GUI does not support obtaining the real name.
2376 Only works when the GUI is running, thus not you your vimrc or
2377 Note that the GTK 2 GUI accepts any font name, thus checking
2378 for a valid name does not work.
2379 gvimrc file. Use the |GUIEnter| autocommand to use this
2380 function just after the GUI has started.
2381
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00002382getfperm({fname}) *getfperm()*
2383 The result is a String, which is the read, write, and execute
2384 permissions of the given file {fname}.
2385 If {fname} does not exist or its directory cannot be read, an
2386 empty string is returned.
2387 The result is of the form "rwxrwxrwx", where each group of
2388 "rwx" flags represent, in turn, the permissions of the owner
2389 of the file, the group the file belongs to, and other users.
2390 If a user does not have a given permission the flag for this
2391 is replaced with the string "-". Example: >
2392 :echo getfperm("/etc/passwd")
2393< This will hopefully (from a security point of view) display
2394 the string "rw-r--r--" or even "rw-------".
2395
Bram Moolenaar071d4272004-06-13 20:20:40 +00002396getftime({fname}) *getftime()*
2397 The result is a Number, which is the last modification time of
2398 the given file {fname}. The value is measured as seconds
2399 since 1st Jan 1970, and may be passed to strftime(). See also
2400 |localtime()| and |strftime()|.
2401 If the file {fname} can't be found -1 is returned.
2402
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00002403getftype({fname}) *getftype()*
2404 The result is a String, which is a description of the kind of
2405 file of the given file {fname}.
2406 If {fname} does not exist an empty string is returned.
2407 Here is a table over different kinds of files and their
2408 results:
2409 Normal file "file"
2410 Directory "dir"
2411 Symbolic link "link"
2412 Block device "bdev"
2413 Character device "cdev"
2414 Socket "socket"
2415 FIFO "fifo"
2416 All other "other"
2417 Example: >
2418 getftype("/home")
2419< Note that a type such as "link" will only be returned on
2420 systems that support it. On some systems only "dir" and
2421 "file" are returned.
2422
Bram Moolenaar071d4272004-06-13 20:20:40 +00002423 *getline()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002424getline({lnum} [, {end}])
2425 Without {end} the result is a String, which is line {lnum}
2426 from the current buffer. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002427 getline(1)
2428< When {lnum} is a String that doesn't start with a
2429 digit, line() is called to translate the String into a Number.
2430 To get the line under the cursor: >
2431 getline(".")
2432< When {lnum} is smaller than 1 or bigger than the number of
2433 lines in the buffer, an empty string is returned.
2434
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002435 When {end} is given the result is a List where each item is a
2436 line from the current buffer in the range {lnum} to {end},
2437 including line {end}.
2438 {end} is used in the same way as {lnum}.
2439 Non-existing lines are silently omitted.
2440 When {end} is before {lnum} an error is given.
2441 Example: >
2442 :let start = line('.')
2443 :let end = search("^$") - 1
2444 :let lines = getline(start, end)
2445
2446
Bram Moolenaar071d4272004-06-13 20:20:40 +00002447getreg([{regname}]) *getreg()*
2448 The result is a String, which is the contents of register
2449 {regname}. Example: >
2450 :let cliptext = getreg('*')
2451< getreg('=') returns the last evaluated value of the expression
2452 register. (For use in maps).
2453 If {regname} is not specified, |v:register| is used.
2454
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002455
Bram Moolenaar071d4272004-06-13 20:20:40 +00002456getregtype([{regname}]) *getregtype()*
2457 The result is a String, which is type of register {regname}.
2458 The value will be one of:
2459 "v" for |characterwise| text
2460 "V" for |linewise| text
2461 "<CTRL-V>{width}" for |blockwise-visual| text
2462 0 for an empty or unknown register
2463 <CTRL-V> is one character with value 0x16.
2464 If {regname} is not specified, |v:register| is used.
2465
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002466
Bram Moolenaar071d4272004-06-13 20:20:40 +00002467 *getwinposx()*
2468getwinposx() The result is a Number, which is the X coordinate in pixels of
2469 the left hand side of the GUI Vim window. The result will be
2470 -1 if the information is not available.
2471
2472 *getwinposy()*
2473getwinposy() The result is a Number, which is the Y coordinate in pixels of
2474 the top of the GUI Vim window. The result will be -1 if the
2475 information is not available.
2476
2477getwinvar({nr}, {varname}) *getwinvar()*
2478 The result is the value of option or local window variable
2479 {varname} in window {nr}.
2480 This also works for a global or local buffer option, but it
2481 doesn't work for a global or local buffer variable.
2482 Note that the name without "w:" must be used.
2483 Examples: >
2484 :let list_is_on = getwinvar(2, '&list')
2485 :echo "myvar = " . getwinvar(1, 'myvar')
2486<
2487 *glob()*
2488glob({expr}) Expand the file wildcards in {expr}. The result is a String.
2489 When there are several matches, they are separated by <NL>
2490 characters.
2491 If the expansion fails, the result is an empty string.
2492 A name for a non-existing file is not included.
2493
2494 For most systems backticks can be used to get files names from
2495 any external command. Example: >
2496 :let tagfiles = glob("`find . -name tags -print`")
2497 :let &tags = substitute(tagfiles, "\n", ",", "g")
2498< The result of the program inside the backticks should be one
2499 item per line. Spaces inside an item are allowed.
2500
2501 See |expand()| for expanding special Vim variables. See
2502 |system()| for getting the raw output of an external command.
2503
2504globpath({path}, {expr}) *globpath()*
2505 Perform glob() on all directories in {path} and concatenate
2506 the results. Example: >
2507 :echo globpath(&rtp, "syntax/c.vim")
2508< {path} is a comma-separated list of directory names. Each
2509 directory name is prepended to {expr} and expanded like with
2510 glob(). A path separator is inserted when needed.
2511 To add a comma inside a directory name escape it with a
2512 backslash. Note that on MS-Windows a directory may have a
2513 trailing backslash, remove it if you put a comma after it.
2514 If the expansion fails for one of the directories, there is no
2515 error message.
2516 The 'wildignore' option applies: Names matching one of the
2517 patterns in 'wildignore' will be skipped.
2518
2519 *has()*
2520has({feature}) The result is a Number, which is 1 if the feature {feature} is
2521 supported, zero otherwise. The {feature} argument is a
2522 string. See |feature-list| below.
2523 Also see |exists()|.
2524
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002525
2526has_key({dict}, {key}) *has_key()*
2527 The result is a Number, which is 1 if Dictionary {dict} has an
2528 entry with key {key}. Zero otherwise.
2529
2530
Bram Moolenaar071d4272004-06-13 20:20:40 +00002531hasmapto({what} [, {mode}]) *hasmapto()*
2532 The result is a Number, which is 1 if there is a mapping that
2533 contains {what} in somewhere in the rhs (what it is mapped to)
2534 and this mapping exists in one of the modes indicated by
2535 {mode}.
2536 Both the global mappings and the mappings local to the current
2537 buffer are checked for a match.
2538 If no matching mapping is found 0 is returned.
2539 The following characters are recognized in {mode}:
2540 n Normal mode
2541 v Visual mode
2542 o Operator-pending mode
2543 i Insert mode
2544 l Language-Argument ("r", "f", "t", etc.)
2545 c Command-line mode
2546 When {mode} is omitted, "nvo" is used.
2547
2548 This function is useful to check if a mapping already exists
2549 to a function in a Vim script. Example: >
2550 :if !hasmapto('\ABCdoit')
2551 : map <Leader>d \ABCdoit
2552 :endif
2553< This installs the mapping to "\ABCdoit" only if there isn't
2554 already a mapping to "\ABCdoit".
2555
2556histadd({history}, {item}) *histadd()*
2557 Add the String {item} to the history {history} which can be
2558 one of: *hist-names*
2559 "cmd" or ":" command line history
2560 "search" or "/" search pattern history
2561 "expr" or "=" typed expression history
2562 "input" or "@" input line history
2563 If {item} does already exist in the history, it will be
2564 shifted to become the newest entry.
2565 The result is a Number: 1 if the operation was successful,
2566 otherwise 0 is returned.
2567
2568 Example: >
2569 :call histadd("input", strftime("%Y %b %d"))
2570 :let date=input("Enter date: ")
2571< This function is not available in the |sandbox|.
2572
2573histdel({history} [, {item}]) *histdel()*
2574 Clear {history}, ie. delete all its entries. See |hist-names|
2575 for the possible values of {history}.
2576
2577 If the parameter {item} is given as String, this is seen
2578 as regular expression. All entries matching that expression
2579 will be removed from the history (if there are any).
2580 Upper/lowercase must match, unless "\c" is used |/\c|.
2581 If {item} is a Number, it will be interpreted as index, see
2582 |:history-indexing|. The respective entry will be removed
2583 if it exists.
2584
2585 The result is a Number: 1 for a successful operation,
2586 otherwise 0 is returned.
2587
2588 Examples:
2589 Clear expression register history: >
2590 :call histdel("expr")
2591<
2592 Remove all entries starting with "*" from the search history: >
2593 :call histdel("/", '^\*')
2594<
2595 The following three are equivalent: >
2596 :call histdel("search", histnr("search"))
2597 :call histdel("search", -1)
2598 :call histdel("search", '^'.histget("search", -1).'$')
2599<
2600 To delete the last search pattern and use the last-but-one for
2601 the "n" command and 'hlsearch': >
2602 :call histdel("search", -1)
2603 :let @/ = histget("search", -1)
2604
2605histget({history} [, {index}]) *histget()*
2606 The result is a String, the entry with Number {index} from
2607 {history}. See |hist-names| for the possible values of
2608 {history}, and |:history-indexing| for {index}. If there is
2609 no such entry, an empty String is returned. When {index} is
2610 omitted, the most recent item from the history is used.
2611
2612 Examples:
2613 Redo the second last search from history. >
2614 :execute '/' . histget("search", -2)
2615
2616< Define an Ex command ":H {num}" that supports re-execution of
2617 the {num}th entry from the output of |:history|. >
2618 :command -nargs=1 H execute histget("cmd", 0+<args>)
2619<
2620histnr({history}) *histnr()*
2621 The result is the Number of the current entry in {history}.
2622 See |hist-names| for the possible values of {history}.
2623 If an error occurred, -1 is returned.
2624
2625 Example: >
2626 :let inp_index = histnr("expr")
2627<
2628hlexists({name}) *hlexists()*
2629 The result is a Number, which is non-zero if a highlight group
2630 called {name} exists. This is when the group has been
2631 defined in some way. Not necessarily when highlighting has
2632 been defined for it, it may also have been used for a syntax
2633 item.
2634 *highlight_exists()*
2635 Obsolete name: highlight_exists().
2636
2637 *hlID()*
2638hlID({name}) The result is a Number, which is the ID of the highlight group
2639 with name {name}. When the highlight group doesn't exist,
2640 zero is returned.
2641 This can be used to retrieve information about the highlight
2642 group. For example, to get the background color of the
2643 "Comment" group: >
2644 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
2645< *highlightID()*
2646 Obsolete name: highlightID().
2647
2648hostname() *hostname()*
2649 The result is a String, which is the name of the machine on
2650 which Vim is currently running. Machine names greater than
2651 256 characters long are truncated.
2652
2653iconv({expr}, {from}, {to}) *iconv()*
2654 The result is a String, which is the text {expr} converted
2655 from encoding {from} to encoding {to}.
2656 When the conversion fails an empty string is returned.
2657 The encoding names are whatever the iconv() library function
2658 can accept, see ":!man 3 iconv".
2659 Most conversions require Vim to be compiled with the |+iconv|
2660 feature. Otherwise only UTF-8 to latin1 conversion and back
2661 can be done.
2662 This can be used to display messages with special characters,
2663 no matter what 'encoding' is set to. Write the message in
2664 UTF-8 and use: >
2665 echo iconv(utf8_str, "utf-8", &enc)
2666< Note that Vim uses UTF-8 for all Unicode encodings, conversion
2667 from/to UCS-2 is automatically changed to use UTF-8. You
2668 cannot use UCS-2 in a string anyway, because of the NUL bytes.
2669 {only available when compiled with the +multi_byte feature}
2670
2671 *indent()*
2672indent({lnum}) The result is a Number, which is indent of line {lnum} in the
2673 current buffer. The indent is counted in spaces, the value
2674 of 'tabstop' is relevant. {lnum} is used just like in
2675 |getline()|.
2676 When {lnum} is invalid -1 is returned.
2677
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002678
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002679index({list}, {expr} [, {start} [, {ic}]]) *index()*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002680 Return the lowest index in List {list} where the item has a
2681 value equal to {expr}.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002682 If {start} is given then skip items with a lower index.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002683 When {ic} is given and it is non-zero, ignore case. Otherwise
2684 case must match.
2685 -1 is returned when {expr} is not found in {list}.
2686 Example: >
2687 :let idx = index(words, "the")
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00002688 :if index(numbers, 123) >= 0
Bram Moolenaarde8866b2005-01-06 23:24:37 +00002689
2690
Bram Moolenaar071d4272004-06-13 20:20:40 +00002691input({prompt} [, {text}]) *input()*
2692 The result is a String, which is whatever the user typed on
2693 the command-line. The parameter is either a prompt string, or
2694 a blank string (for no prompt). A '\n' can be used in the
2695 prompt to start a new line. The highlighting set with
2696 |:echohl| is used for the prompt. The input is entered just
2697 like a command-line, with the same editing commands and
2698 mappings. There is a separate history for lines typed for
2699 input().
2700 If the optional {text} is present, this is used for the
2701 default reply, as if the user typed this.
2702 NOTE: This must not be used in a startup file, for the
2703 versions that only run in GUI mode (e.g., the Win32 GUI).
2704 Note: When input() is called from within a mapping it will
2705 consume remaining characters from that mapping, because a
2706 mapping is handled like the characters were typed.
2707 Use |inputsave()| before input() and |inputrestore()|
2708 after input() to avoid that. Another solution is to avoid
2709 that further characters follow in the mapping, e.g., by using
2710 |:execute| or |:normal|.
2711
2712 Example: >
2713 :if input("Coffee or beer? ") == "beer"
2714 : echo "Cheers!"
2715 :endif
2716< Example with default text: >
2717 :let color = input("Color? ", "white")
2718< Example with a mapping: >
2719 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR>
2720 :function GetFoo()
2721 : call inputsave()
2722 : let g:Foo = input("enter search pattern: ")
2723 : call inputrestore()
2724 :endfunction
2725
2726inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
2727 Like input(), but when the GUI is running and text dialogs are
2728 supported, a dialog window pops up to input the text.
2729 Example: >
2730 :let n = inputdialog("value for shiftwidth", &sw)
2731 :if n != ""
2732 : let &sw = n
2733 :endif
2734< When the dialog is cancelled {cancelreturn} is returned. When
2735 omitted an empty string is returned.
2736 Hitting <Enter> works like pressing the OK button. Hitting
2737 <Esc> works like pressing the Cancel button.
2738
2739inputrestore() *inputrestore()*
2740 Restore typeahead that was saved with a previous inputsave().
2741 Should be called the same number of times inputsave() is
2742 called. Calling it more often is harmless though.
2743 Returns 1 when there is nothing to restore, 0 otherwise.
2744
2745inputsave() *inputsave()*
2746 Preserve typeahead (also from mappings) and clear it, so that
2747 a following prompt gets input from the user. Should be
2748 followed by a matching inputrestore() after the prompt. Can
2749 be used several times, in which case there must be just as
2750 many inputrestore() calls.
2751 Returns 1 when out of memory, 0 otherwise.
2752
2753inputsecret({prompt} [, {text}]) *inputsecret()*
2754 This function acts much like the |input()| function with but
2755 two exceptions:
2756 a) the user's response will be displayed as a sequence of
2757 asterisks ("*") thereby keeping the entry secret, and
2758 b) the user's response will not be recorded on the input
2759 |history| stack.
2760 The result is a String, which is whatever the user actually
2761 typed on the command-line in response to the issued prompt.
2762
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002763insert({list}, {item} [, {idx}]) *insert()*
2764 Insert {item} at the start of List {list}.
2765 If {idx} is specified insert {item} before the item with index
2766 {idx}. If {idx} is zero it goes before the first item, just
2767 like omitting {idx}. A negative {idx} is also possible, see
2768 |list-index|. -1 inserts just before the last item.
2769 Returns the resulting List. Examples: >
2770 :let mylist = insert([2, 3, 5], 1)
2771 :call insert(mylist, 4, -1)
2772 :call insert(mylist, 6, len(mylist))
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002773< The last example can be done simpler with |add()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002774 Note that when {item} is a List it is inserted as a single
2775 item. Use |extend()| to concatenate Lists.
2776
Bram Moolenaar071d4272004-06-13 20:20:40 +00002777isdirectory({directory}) *isdirectory()*
2778 The result is a Number, which is non-zero when a directory
2779 with the name {directory} exists. If {directory} doesn't
2780 exist, or isn't a directory, the result is FALSE. {directory}
2781 is any expression, which is used as a String.
2782
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002783
2784join({list} [, {sep}]) *join()*
2785 Join the items in {list} together into one String.
2786 When {sep} is specified it is put in between the items. If
2787 {sep} is omitted a single space is used.
2788 Note that {sep} is not added at the end. You might want to
2789 add it there too: >
2790 let lines = join(mylist, "\n") . "\n"
2791< String items are used as-is. Lists and Dictionaries are
2792 converted into a string like with |string()|.
2793 The opposite function is |split()|.
2794
Bram Moolenaard8b02732005-01-14 21:48:43 +00002795keys({dict}) *keys()*
2796 Return a List with all the keys of {dict}. The List is in
2797 arbitrary order.
2798
Bram Moolenaar13065c42005-01-08 16:08:21 +00002799 *len()* *E701*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002800len({expr}) The result is a Number, which is the length of the argument.
2801 When {expr} is a String or a Number the length in bytes is
2802 used, as with |strlen()|.
2803 When {expr} is a List the number of items in the List is
2804 returned.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002805 When {expr} is a Dictionary the number of entries in the
2806 Dictionary is returned.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002807 Otherwise an error is given.
2808
Bram Moolenaar071d4272004-06-13 20:20:40 +00002809 *libcall()* *E364* *E368*
2810libcall({libname}, {funcname}, {argument})
2811 Call function {funcname} in the run-time library {libname}
2812 with single argument {argument}.
2813 This is useful to call functions in a library that you
2814 especially made to be used with Vim. Since only one argument
2815 is possible, calling standard library functions is rather
2816 limited.
2817 The result is the String returned by the function. If the
2818 function returns NULL, this will appear as an empty string ""
2819 to Vim.
2820 If the function returns a number, use libcallnr()!
2821 If {argument} is a number, it is passed to the function as an
2822 int; if {argument} is a string, it is passed as a
2823 null-terminated string.
2824 This function will fail in |restricted-mode|.
2825
2826 libcall() allows you to write your own 'plug-in' extensions to
2827 Vim without having to recompile the program. It is NOT a
2828 means to call system functions! If you try to do so Vim will
2829 very probably crash.
2830
2831 For Win32, the functions you write must be placed in a DLL
2832 and use the normal C calling convention (NOT Pascal which is
2833 used in Windows System DLLs). The function must take exactly
2834 one parameter, either a character pointer or a long integer,
2835 and must return a character pointer or NULL. The character
2836 pointer returned must point to memory that will remain valid
2837 after the function has returned (e.g. in static data in the
2838 DLL). If it points to allocated memory, that memory will
2839 leak away. Using a static buffer in the function should work,
2840 it's then freed when the DLL is unloaded.
2841
2842 WARNING: If the function returns a non-valid pointer, Vim may
2843 crash! This also happens if the function returns a number,
2844 because Vim thinks it's a pointer.
2845 For Win32 systems, {libname} should be the filename of the DLL
2846 without the ".DLL" suffix. A full path is only required if
2847 the DLL is not in the usual places.
2848 For Unix: When compiling your own plugins, remember that the
2849 object code must be compiled as position-independent ('PIC').
2850 {only in Win32 on some Unix versions, when the |+libcall|
2851 feature is present}
2852 Examples: >
2853 :echo libcall("libc.so", "getenv", "HOME")
2854 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
2855<
2856 *libcallnr()*
2857libcallnr({libname}, {funcname}, {argument})
2858 Just like libcall(), but used for a function that returns an
2859 int instead of a string.
2860 {only in Win32 on some Unix versions, when the |+libcall|
2861 feature is present}
2862 Example (not very useful...): >
2863 :call libcallnr("libc.so", "printf", "Hello World!\n")
2864 :call libcallnr("libc.so", "sleep", 10)
2865<
2866 *line()*
2867line({expr}) The result is a Number, which is the line number of the file
2868 position given with {expr}. The accepted positions are:
2869 . the cursor position
2870 $ the last line in the current buffer
2871 'x position of mark x (if the mark is not set, 0 is
2872 returned)
2873 Note that only marks in the current file can be used.
2874 Examples: >
2875 line(".") line number of the cursor
2876 line("'t") line number of mark t
2877 line("'" . marker) line number of mark marker
2878< *last-position-jump*
2879 This autocommand jumps to the last known position in a file
2880 just after opening it, if the '" mark is set: >
2881 :au BufReadPost * if line("'\"") > 0 && line("'\"") <= line("$") | exe "normal g'\"" | endif
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00002882
Bram Moolenaar071d4272004-06-13 20:20:40 +00002883line2byte({lnum}) *line2byte()*
2884 Return the byte count from the start of the buffer for line
2885 {lnum}. This includes the end-of-line character, depending on
2886 the 'fileformat' option for the current buffer. The first
2887 line returns 1.
2888 This can also be used to get the byte count for the line just
2889 below the last line: >
2890 line2byte(line("$") + 1)
2891< This is the file size plus one.
2892 When {lnum} is invalid, or the |+byte_offset| feature has been
2893 disabled at compile time, -1 is returned.
2894 Also see |byte2line()|, |go| and |:goto|.
2895
2896lispindent({lnum}) *lispindent()*
2897 Get the amount of indent for line {lnum} according the lisp
2898 indenting rules, as with 'lisp'.
2899 The indent is counted in spaces, the value of 'tabstop' is
2900 relevant. {lnum} is used just like in |getline()|.
2901 When {lnum} is invalid or Vim was not compiled the
2902 |+lispindent| feature, -1 is returned.
2903
2904localtime() *localtime()*
2905 Return the current time, measured as seconds since 1st Jan
2906 1970. See also |strftime()| and |getftime()|.
2907
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002908
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002909map({expr}, {string}) *map()*
2910 {expr} must be a List or a Dictionary.
2911 Replace each item in {expr} with the result of evaluating
2912 {string}.
2913 Inside {string} |v:val| has the value of the current item.
2914 For a Dictionary |v:key| has the key of the current item.
2915 Example: >
2916 :call map(mylist, '"> " . v:val . " <"')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002917< This puts "> " before and " <" after each item in "mylist".
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002918
2919 Note that {string} is the result of expression and is then
2920 used as an expression again. Often it is good to use a
2921 |literal-string| to avoid having to double backslashes.
2922
2923 The operation is done in-place. If you want a List or
2924 Dictionary to remain unmodified make a copy first: >
Bram Moolenaard8b02732005-01-14 21:48:43 +00002925 :let tlist = map(copy(mylist), ' & . "\t"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002926
2927< Returns {expr}, the List or Dictionary that was filtered.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002928
2929
Bram Moolenaar071d4272004-06-13 20:20:40 +00002930maparg({name}[, {mode}]) *maparg()*
2931 Return the rhs of mapping {name} in mode {mode}. When there
2932 is no mapping for {name}, an empty String is returned.
2933 These characters can be used for {mode}:
2934 "n" Normal
2935 "v" Visual
2936 "o" Operator-pending
2937 "i" Insert
2938 "c" Cmd-line
2939 "l" langmap |language-mapping|
2940 "" Normal, Visual and Operator-pending
2941 When {mode} is omitted, the modes from "" are used.
2942 The {name} can have special key names, like in the ":map"
2943 command. The returned String has special characters
2944 translated like in the output of the ":map" command listing.
2945 The mappings local to the current buffer are checked first,
2946 then the global mappings.
2947
2948mapcheck({name}[, {mode}]) *mapcheck()*
2949 Check if there is a mapping that matches with {name} in mode
2950 {mode}. See |maparg()| for {mode} and special names in
2951 {name}.
2952 A match happens with a mapping that starts with {name} and
2953 with a mapping which is equal to the start of {name}.
2954
2955 matches mapping "a" "ab" "abc" ~
2956 mapcheck("a") yes yes yes
2957 mapcheck("abc") yes yes yes
2958 mapcheck("ax") yes no no
2959 mapcheck("b") no no no
2960
2961 The difference with maparg() is that mapcheck() finds a
2962 mapping that matches with {name}, while maparg() only finds a
2963 mapping for {name} exactly.
2964 When there is no mapping that starts with {name}, an empty
2965 String is returned. If there is one, the rhs of that mapping
2966 is returned. If there are several mappings that start with
2967 {name}, the rhs of one of them is returned.
2968 The mappings local to the current buffer are checked first,
2969 then the global mappings.
2970 This function can be used to check if a mapping can be added
2971 without being ambiguous. Example: >
2972 :if mapcheck("_vv") == ""
2973 : map _vv :set guifont=7x13<CR>
2974 :endif
2975< This avoids adding the "_vv" mapping when there already is a
2976 mapping for "_v" or for "_vvv".
2977
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002978match({expr}, {pat}[, {start}[, {count}]]) *match()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002979 When {expr} is a List then this returns the index of the first
2980 item where {pat} matches. Each item is used as a String,
2981 Lists and Dictionaries are used as echoed.
2982 Otherwise, {expr} is used as a String. The result is a
2983 Number, which gives the index (byte offset) in {expr} where
2984 {pat} matches.
2985 A match at the first character or List item returns zero.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002986 If there is no match -1 is returned.
2987 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002988 :echo match("testing", "ing") " results in 4
2989 :echo match([1, 'x'], '\a') " results in 2
2990< See |string-match| for how {pat} is used.
2991
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002992 When {count} is given use the {count}'th match. When a match
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002993 is found in a String the search for the next one starts on
2994 character further. Thus this example results in 1: >
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002995 echo match("testing", "..", 0, 2)
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00002996< In a List the search continues in the next item.
2997
2998 If {start} is given, the search starts from byte index
2999 {start} in a String or item {start} in a List.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003000 The result, however, is still the index counted from the
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003001 first character/item. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003002 :echo match("testing", "ing", 2)
3003< result is again "4". >
3004 :echo match("testing", "ing", 4)
3005< result is again "4". >
3006 :echo match("testing", "t", 2)
3007< result is "3".
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003008 For a String, if {start} < 0, it will be set to 0. For a list
3009 the index is counted from the end.
3010 If {start} is out of range (> strlen({expr} for a String or
3011 > len({expr} for a List) -1 is returned.
3012
Bram Moolenaar071d4272004-06-13 20:20:40 +00003013 See |pattern| for the patterns that are accepted.
3014 The 'ignorecase' option is used to set the ignore-caseness of
3015 the pattern. 'smartcase' is NOT used. The matching is always
3016 done like 'magic' is set and 'cpoptions' is empty.
3017
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003018matchend({expr}, {pat}[, {start}[, {count}]]) *matchend()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003019 Same as match(), but return the index of first character after
3020 the match. Example: >
3021 :echo matchend("testing", "ing")
3022< results in "7".
3023 The {start}, if given, has the same meaning as for match(). >
3024 :echo matchend("testing", "ing", 2)
3025< results in "7". >
3026 :echo matchend("testing", "ing", 5)
3027< result is "-1".
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003028 When {expr} is a List the result is equal to match().
Bram Moolenaar071d4272004-06-13 20:20:40 +00003029
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00003030matchstr({expr}, {pat}[, {start}[, {count}]]) *matchstr()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003031 Same as match(), but return the matched string. Example: >
3032 :echo matchstr("testing", "ing")
3033< results in "ing".
3034 When there is no match "" is returned.
3035 The {start}, if given, has the same meaning as for match(). >
3036 :echo matchstr("testing", "ing", 2)
3037< results in "ing". >
3038 :echo matchstr("testing", "ing", 5)
3039< result is "".
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003040 When {expr} is a List then the matching item is returned.
3041 The type isn't changed, it's not necessarily a String.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003042
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00003043 *max()*
3044max({list}) Return the maximum value of all items in {list}.
3045 If {list} is not a list or one of the items in {list} cannot
3046 be used as a Number this results in an error.
3047 An empty List results in zero.
3048
3049 *min()*
3050min({list}) Return the minumum value of all items in {list}.
3051 If {list} is not a list or one of the items in {list} cannot
3052 be used as a Number this results in an error.
3053 An empty List results in zero.
3054
Bram Moolenaar071d4272004-06-13 20:20:40 +00003055 *mode()*
3056mode() Return a string that indicates the current mode:
3057 n Normal
3058 v Visual by character
3059 V Visual by line
3060 CTRL-V Visual blockwise
3061 s Select by character
3062 S Select by line
3063 CTRL-S Select blockwise
3064 i Insert
3065 R Replace
3066 c Command-line
3067 r Hit-enter prompt
3068 This is useful in the 'statusline' option. In most other
3069 places it always returns "c" or "n".
3070
3071nextnonblank({lnum}) *nextnonblank()*
3072 Return the line number of the first line at or below {lnum}
3073 that is not blank. Example: >
3074 if getline(nextnonblank(1)) =~ "Java"
3075< When {lnum} is invalid or there is no non-blank line at or
3076 below it, zero is returned.
3077 See also |prevnonblank()|.
3078
3079nr2char({expr}) *nr2char()*
3080 Return a string with a single character, which has the number
3081 value {expr}. Examples: >
3082 nr2char(64) returns "@"
3083 nr2char(32) returns " "
3084< The current 'encoding' is used. Example for "utf-8": >
3085 nr2char(300) returns I with bow character
3086< Note that a NUL character in the file is specified with
3087 nr2char(10), because NULs are represented with newline
3088 characters. nr2char(0) is a real NUL and terminates the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00003089 string, thus results in an empty string.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003090
3091prevnonblank({lnum}) *prevnonblank()*
3092 Return the line number of the first line at or above {lnum}
3093 that is not blank. Example: >
3094 let ind = indent(prevnonblank(v:lnum - 1))
3095< When {lnum} is invalid or there is no non-blank line at or
3096 above it, zero is returned.
3097 Also see |nextnonblank()|.
3098
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003099 *E726* *E727*
Bram Moolenaard8b02732005-01-14 21:48:43 +00003100range({expr} [, {max} [, {stride}]]) *range()*
3101 Returns a List with Numbers:
3102 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
3103 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
3104 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
3105 {max}] (increasing {expr} with {stride} each time, not
3106 producing a value past {max}).
3107 Examples: >
3108 range(4) " [0, 1, 2, 3]
3109 range(2, 4) " [2, 3, 4]
3110 range(2, 9, 3) " [2, 5, 8]
3111 range(2, -2, -1) " [2, 1, 0, -1, -2]
3112<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003113 *remote_expr()* *E449*
3114remote_expr({server}, {string} [, {idvar}])
3115 Send the {string} to {server}. The string is sent as an
3116 expression and the result is returned after evaluation.
3117 If {idvar} is present, it is taken as the name of a
3118 variable and a {serverid} for later use with
3119 remote_read() is stored there.
3120 See also |clientserver| |RemoteReply|.
3121 This function is not available in the |sandbox|.
3122 {only available when compiled with the |+clientserver| feature}
3123 Note: Any errors will cause a local error message to be issued
3124 and the result will be the empty string.
3125 Examples: >
3126 :echo remote_expr("gvim", "2+2")
3127 :echo remote_expr("gvim1", "b:current_syntax")
3128<
3129
3130remote_foreground({server}) *remote_foreground()*
3131 Move the Vim server with the name {server} to the foreground.
3132 This works like: >
3133 remote_expr({server}, "foreground()")
3134< Except that on Win32 systems the client does the work, to work
3135 around the problem that the OS doesn't always allow the server
3136 to bring itself to the foreground.
3137 This function is not available in the |sandbox|.
3138 {only in the Win32, Athena, Motif and GTK GUI versions and the
3139 Win32 console version}
3140
3141
3142remote_peek({serverid} [, {retvar}]) *remote_peek()*
3143 Returns a positive number if there are available strings
3144 from {serverid}. Copies any reply string into the variable
3145 {retvar} if specified. {retvar} must be a string with the
3146 name of a variable.
3147 Returns zero if none are available.
3148 Returns -1 if something is wrong.
3149 See also |clientserver|.
3150 This function is not available in the |sandbox|.
3151 {only available when compiled with the |+clientserver| feature}
3152 Examples: >
3153 :let repl = ""
3154 :echo "PEEK: ".remote_peek(id, "repl").": ".repl
3155
3156remote_read({serverid}) *remote_read()*
3157 Return the oldest available reply from {serverid} and consume
3158 it. It blocks until a reply is available.
3159 See also |clientserver|.
3160 This function is not available in the |sandbox|.
3161 {only available when compiled with the |+clientserver| feature}
3162 Example: >
3163 :echo remote_read(id)
3164<
3165 *remote_send()* *E241*
3166remote_send({server}, {string} [, {idvar}])
Bram Moolenaard4755bb2004-09-02 19:12:26 +00003167 Send the {string} to {server}. The string is sent as input
3168 keys and the function returns immediately. At the Vim server
3169 the keys are not mapped |:map|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003170 If {idvar} is present, it is taken as the name of a
3171 variable and a {serverid} for later use with
3172 remote_read() is stored there.
3173 See also |clientserver| |RemoteReply|.
3174 This function is not available in the |sandbox|.
3175 {only available when compiled with the |+clientserver| feature}
3176 Note: Any errors will be reported in the server and may mess
3177 up the display.
3178 Examples: >
3179 :echo remote_send("gvim", ":DropAndReply ".file, "serverid").
3180 \ remote_read(serverid)
3181
3182 :autocmd NONE RemoteReply *
3183 \ echo remote_read(expand("<amatch>"))
3184 :echo remote_send("gvim", ":sleep 10 | echo ".
3185 \ 'server2client(expand("<client>"), "HELLO")<CR>')
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003186<
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003187remove({list}, {idx} [, {end}]) *remove()*
3188 Without {end}: Remove the item at {idx} from List {list} and
3189 return it.
3190 With {end}: Remove items from {idx} to {end} (inclusive) and
3191 return a list with these items. When {idx} points to the same
3192 item as {end} a list with one item is returned. When {end}
3193 points to an item before {idx} this is an error.
3194 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003195 Example: >
3196 :echo "last item: " . remove(mylist, -1)
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003197 :call remove(mylist, 0, 9)
Bram Moolenaard8b02732005-01-14 21:48:43 +00003198remove({dict}, {key})
3199 Remove the entry from {dict} with key {key}. Example: >
3200 :echo "removed " . remove(dict, "one")
3201< If there is no {key} in {dict} this is an error.
3202
3203 Use |delete()| to remove a file.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003204
Bram Moolenaar071d4272004-06-13 20:20:40 +00003205rename({from}, {to}) *rename()*
3206 Rename the file by the name {from} to the name {to}. This
3207 should also work to move files across file systems. The
3208 result is a Number, which is 0 if the file was renamed
3209 successfully, and non-zero when the renaming failed.
3210 This function is not available in the |sandbox|.
3211
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003212repeat({expr}, {count}) *repeat()*
3213 Repeat {expr} {count} times and return the concatenated
3214 result. Example: >
3215 :let seperator = repeat('-', 80)
3216< When {count} is zero or negative the result is empty.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00003217 When {expr} is a List the result is {expr} concatenated
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003218 {count} times. Example: >
3219 :let longlist = repeat(['a', 'b'], 3)
3220< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003221
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003222
Bram Moolenaar071d4272004-06-13 20:20:40 +00003223resolve({filename}) *resolve()* *E655*
3224 On MS-Windows, when {filename} is a shortcut (a .lnk file),
3225 returns the path the shortcut points to in a simplified form.
3226 On Unix, repeat resolving symbolic links in all path
3227 components of {filename} and return the simplified result.
3228 To cope with link cycles, resolving of symbolic links is
3229 stopped after 100 iterations.
3230 On other systems, return the simplified {filename}.
3231 The simplification step is done as by |simplify()|.
3232 resolve() keeps a leading path component specifying the
3233 current directory (provided the result is still a relative
3234 path name) and also keeps a trailing path separator.
3235
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003236 *reverse()*
3237reverse({list}) Reverse the order of items in {list} in-place. Returns
3238 {list}.
3239 If you want a list to remain unmodified make a copy first: >
3240 :let revlist = reverse(copy(mylist))
3241
Bram Moolenaar071d4272004-06-13 20:20:40 +00003242search({pattern} [, {flags}]) *search()*
3243 Search for regexp pattern {pattern}. The search starts at the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00003244 cursor position (you can use |cursor()| to set it).
Bram Moolenaar071d4272004-06-13 20:20:40 +00003245 {flags} is a String, which can contain these character flags:
3246 'b' search backward instead of forward
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003247 'n' do Not move the cursor
Bram Moolenaar071d4272004-06-13 20:20:40 +00003248 'w' wrap around the end of the file
3249 'W' don't wrap around the end of the file
3250 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
3251
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003252 When a match has been found its line number is returned.
3253 The cursor will be positioned at the match, unless the 'n'
3254 flag is used).
3255 If there is no match a 0 is returned and the cursor doesn't
3256 move. No error message is given.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003257
3258 Example (goes over all files in the argument list): >
3259 :let n = 1
3260 :while n <= argc() " loop over all files in arglist
3261 : exe "argument " . n
3262 : " start at the last char in the file and wrap for the
3263 : " first search to find match at start of file
3264 : normal G$
3265 : let flags = "w"
3266 : while search("foo", flags) > 0
3267 : s/foo/bar/g
3268 : let flags = "W"
3269 : endwhile
3270 : update " write the file if modified
3271 : let n = n + 1
3272 :endwhile
3273<
3274 *searchpair()*
3275searchpair({start}, {middle}, {end} [, {flags} [, {skip}]])
3276 Search for the match of a nested start-end pair. This can be
3277 used to find the "endif" that matches an "if", while other
3278 if/endif pairs in between are ignored.
3279 The search starts at the cursor. If a match is found, the
3280 cursor is positioned at it and the line number is returned.
3281 If no match is found 0 or -1 is returned and the cursor
3282 doesn't move. No error message is given.
3283
3284 {start}, {middle} and {end} are patterns, see |pattern|. They
3285 must not contain \( \) pairs. Use of \%( \) is allowed. When
3286 {middle} is not empty, it is found when searching from either
3287 direction, but only when not in a nested start-end pair. A
3288 typical use is: >
3289 searchpair('\<if\>', '\<else\>', '\<endif\>')
3290< By leaving {middle} empty the "else" is skipped.
3291
3292 {flags} are used like with |search()|. Additionally:
3293 'n' do Not move the cursor
3294 'r' Repeat until no more matches found; will find the
3295 outer pair
3296 'm' return number of Matches instead of line number with
3297 the match; will only be > 1 when 'r' is used.
3298
3299 When a match for {start}, {middle} or {end} is found, the
3300 {skip} expression is evaluated with the cursor positioned on
3301 the start of the match. It should return non-zero if this
3302 match is to be skipped. E.g., because it is inside a comment
3303 or a string.
3304 When {skip} is omitted or empty, every match is accepted.
3305 When evaluating {skip} causes an error the search is aborted
3306 and -1 returned.
3307
3308 The value of 'ignorecase' is used. 'magic' is ignored, the
3309 patterns are used like it's on.
3310
3311 The search starts exactly at the cursor. A match with
3312 {start}, {middle} or {end} at the next character, in the
3313 direction of searching, is the first one found. Example: >
3314 if 1
3315 if 2
3316 endif 2
3317 endif 1
3318< When starting at the "if 2", with the cursor on the "i", and
3319 searching forwards, the "endif 2" is found. When starting on
3320 the character just before the "if 2", the "endif 1" will be
3321 found. That's because the "if 2" will be found first, and
3322 then this is considered to be a nested if/endif from "if 2" to
3323 "endif 2".
3324 When searching backwards and {end} is more than one character,
3325 it may be useful to put "\zs" at the end of the pattern, so
3326 that when the cursor is inside a match with the end it finds
3327 the matching start.
3328
3329 Example, to find the "endif" command in a Vim script: >
3330
3331 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
3332 \ 'getline(".") =~ "^\\s*\""')
3333
3334< The cursor must be at or after the "if" for which a match is
3335 to be found. Note that single-quote strings are used to avoid
3336 having to double the backslashes. The skip expression only
3337 catches comments at the start of a line, not after a command.
3338 Also, a word "en" or "if" halfway a line is considered a
3339 match.
3340 Another example, to search for the matching "{" of a "}": >
3341
3342 :echo searchpair('{', '', '}', 'bW')
3343
3344< This works when the cursor is at or before the "}" for which a
3345 match is to be found. To reject matches that syntax
3346 highlighting recognized as strings: >
3347
3348 :echo searchpair('{', '', '}', 'bW',
3349 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
3350<
3351server2client( {clientid}, {string}) *server2client()*
3352 Send a reply string to {clientid}. The most recent {clientid}
3353 that sent a string can be retrieved with expand("<client>").
3354 {only available when compiled with the |+clientserver| feature}
3355 Note:
3356 This id has to be stored before the next command can be
3357 received. Ie. before returning from the received command and
3358 before calling any commands that waits for input.
3359 See also |clientserver|.
3360 Example: >
3361 :echo server2client(expand("<client>"), "HELLO")
3362<
3363serverlist() *serverlist()*
3364 Return a list of available server names, one per line.
3365 When there are no servers or the information is not available
3366 an empty string is returned. See also |clientserver|.
3367 {only available when compiled with the |+clientserver| feature}
3368 Example: >
3369 :echo serverlist()
3370<
3371setbufvar({expr}, {varname}, {val}) *setbufvar()*
3372 Set option or local variable {varname} in buffer {expr} to
3373 {val}.
3374 This also works for a global or local window option, but it
3375 doesn't work for a global or local window variable.
3376 For a local window option the global value is unchanged.
3377 For the use of {expr}, see |bufname()| above.
3378 Note that the variable name without "b:" must be used.
3379 Examples: >
3380 :call setbufvar(1, "&mod", 1)
3381 :call setbufvar("todo", "myvar", "foobar")
3382< This function is not available in the |sandbox|.
3383
3384setcmdpos({pos}) *setcmdpos()*
3385 Set the cursor position in the command line to byte position
3386 {pos}. The first position is 1.
3387 Use |getcmdpos()| to obtain the current position.
3388 Only works while editing the command line, thus you must use
Bram Moolenaard8b02732005-01-14 21:48:43 +00003389 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
3390 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
3391 set after the command line is set to the expression. For
3392 |c_CTRL-R_=| it is set after evaluating the expression but
3393 before inserting the resulting text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003394 When the number is too big the cursor is put at the end of the
3395 line. A number smaller than one has undefined results.
3396 Returns 0 when successful, 1 when not editing the command
3397 line.
3398
3399setline({lnum}, {line}) *setline()*
3400 Set line {lnum} of the current buffer to {line}. If this
3401 succeeds, 0 is returned. If this fails (most likely because
3402 {lnum} is invalid) 1 is returned. Example: >
3403 :call setline(5, strftime("%c"))
3404< Note: The '[ and '] marks are not set.
3405
3406 *setreg()*
3407setreg({regname}, {value} [,{options}])
3408 Set the register {regname} to {value}.
3409 If {options} contains "a" or {regname} is upper case,
3410 then the value is appended.
3411 {options} can also contains a register type specification:
3412 "c" or "v" |characterwise| mode
3413 "l" or "V" |linewise| mode
3414 "b" or "<CTRL-V>" |blockwise-visual| mode
3415 If a number immediately follows "b" or "<CTRL-V>" then this is
3416 used as the width of the selection - if it is not specified
3417 then the width of the block is set to the number of characters
3418 in the longest line (counting a <TAB> as 1 character).
3419
3420 If {options} contains no register settings, then the default
3421 is to use character mode unless {value} ends in a <NL>.
3422 Setting the '=' register is not possible.
3423 Returns zero for success, non-zero for failure.
3424
3425 Examples: >
3426 :call setreg(v:register, @*)
3427 :call setreg('*', @%, 'ac')
3428 :call setreg('a', "1\n2\n3", 'b5')
3429
3430< This example shows using the functions to save and restore a
3431 register. >
3432 :let var_a = getreg('a')
3433 :let var_amode = getregtype('a')
3434 ....
3435 :call setreg('a', var_a, var_amode)
3436
3437< You can also change the type of a register by appending
3438 nothing: >
3439 :call setreg('a', '', 'al')
3440
3441setwinvar({nr}, {varname}, {val}) *setwinvar()*
3442 Set option or local variable {varname} in window {nr} to
3443 {val}.
3444 This also works for a global or local buffer option, but it
3445 doesn't work for a global or local buffer variable.
3446 For a local buffer option the global value is unchanged.
3447 Note that the variable name without "w:" must be used.
3448 Examples: >
3449 :call setwinvar(1, "&list", 0)
3450 :call setwinvar(2, "myvar", "foobar")
3451< This function is not available in the |sandbox|.
3452
3453simplify({filename}) *simplify()*
3454 Simplify the file name as much as possible without changing
3455 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
3456 Unix) are not resolved. If the first path component in
3457 {filename} designates the current directory, this will be
3458 valid for the result as well. A trailing path separator is
3459 not removed either.
3460 Example: >
3461 simplify("./dir/.././/file/") == "./file/"
3462< Note: The combination "dir/.." is only removed if "dir" is
3463 a searchable directory or does not exist. On Unix, it is also
3464 removed when "dir" is a symbolic link within the same
3465 directory. In order to resolve all the involved symbolic
3466 links before simplifying the path name, use |resolve()|.
3467
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003468
Bram Moolenaar13065c42005-01-08 16:08:21 +00003469sort({list} [, {func}]) *sort()* *E702*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003470 Sort the items in {list} in-place. Returns {list}. If you
3471 want a list to remain unmodified make a copy first: >
3472 :let sortedlist = sort(copy(mylist))
3473< Uses the string representation of each item to sort on.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003474 Numbers sort after Strings, Lists after Numbers.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003475 When {func} is given and it is one then case is ignored.
3476 When {func} is a Funcref or a function name, this function is
3477 called to compare items. The function is invoked with two
3478 items as argument and must return zero if they are equal, 1 if
3479 the first one sorts after the second one, -1 if the first one
3480 sorts before the second one. Example: >
3481 func MyCompare(i1, i2)
3482 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
3483 endfunc
3484 let sortedlist = sort(mylist, "MyCompare")
3485
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003486split({expr} [, {pattern}]) *split()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003487 Make a List out of {expr}. When {pattern} is omitted each
3488 white-separated sequence of characters becomes an item.
3489 Otherwise the string is split where {pattern} matches,
3490 removing the matched characters. Empty strings are omitted.
3491 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003492 :let words = split(getline('.'), '\W\+')
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003493< Since empty strings are not added the "\+" isn't required but
3494 it makes the function work a bit faster.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003495 The opposite function is |join()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003496
3497
Bram Moolenaar071d4272004-06-13 20:20:40 +00003498strftime({format} [, {time}]) *strftime()*
3499 The result is a String, which is a formatted date and time, as
3500 specified by the {format} string. The given {time} is used,
3501 or the current time if no time is given. The accepted
3502 {format} depends on your system, thus this is not portable!
3503 See the manual page of the C function strftime() for the
3504 format. The maximum length of the result is 80 characters.
3505 See also |localtime()| and |getftime()|.
3506 The language can be changed with the |:language| command.
3507 Examples: >
3508 :echo strftime("%c") Sun Apr 27 11:49:23 1997
3509 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
3510 :echo strftime("%y%m%d %T") 970427 11:53:55
3511 :echo strftime("%H:%M") 11:55
3512 :echo strftime("%c", getftime("file.c"))
3513 Show mod time of file.c.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00003514< Not available on all systems. To check use: >
3515 :if exists("*strftime")
3516
Bram Moolenaar8f999f12005-01-25 22:12:55 +00003517stridx({haystack}, {needle} [, {start}]) *stridx()*
3518 The result is a Number, which gives the byte index in
3519 {haystack} of the first occurrence of the String {needle}.
3520 If {start} is specified, the String {needle} is searched from
3521 the byte index {start} in the String {haystack}.
3522 The search is done case-sensitive.
3523 For pattern searches use |match()|.
3524 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003525 See also |strridx()|. Examples: >
3526 :echo stridx("An Example", "Example") 3
3527 :echo stridx("Starting point", "Start") 0
3528 :echo stridx("Starting point", "start") -1
3529<
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003530 *string()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003531string({expr}) Return {expr} converted to a String. If {expr} is a Number,
3532 String or a composition of them, then the result can be parsed
3533 back with |eval()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003534 {expr} type result ~
Bram Moolenaard8b02732005-01-14 21:48:43 +00003535 String 'string'
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003536 Number 123
Bram Moolenaard8b02732005-01-14 21:48:43 +00003537 Funcref function('name')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003538 List [item, item]
Bram Moolenaard8b02732005-01-14 21:48:43 +00003539 Note that in String values the ' character is doubled.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003540
Bram Moolenaar071d4272004-06-13 20:20:40 +00003541 *strlen()*
3542strlen({expr}) The result is a Number, which is the length of the String
3543 {expr} in bytes. If you want to count the number of
3544 multi-byte characters use something like this: >
3545
3546 :let len = strlen(substitute(str, ".", "x", "g"))
3547
3548< Composing characters are not counted.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003549 If the argument is a Number it is first converted to a String.
3550 For other types an error is given.
3551 Also see |len()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003552
3553strpart({src}, {start}[, {len}]) *strpart()*
3554 The result is a String, which is part of {src}, starting from
3555 byte {start}, with the length {len}.
3556 When non-existing bytes are included, this doesn't result in
3557 an error, the bytes are simply omitted.
3558 If {len} is missing, the copy continues from {start} till the
3559 end of the {src}. >
3560 strpart("abcdefg", 3, 2) == "de"
3561 strpart("abcdefg", -2, 4) == "ab"
3562 strpart("abcdefg", 5, 4) == "fg"
3563 strpart("abcdefg", 3) == "defg"
3564< Note: To get the first character, {start} must be 0. For
3565 example, to get three bytes under and after the cursor: >
3566 strpart(getline(line(".")), col(".") - 1, 3)
3567<
3568strridx({haystack}, {needle}) *strridx()*
3569 The result is a Number, which gives the index in {haystack} of
Bram Moolenaar8f999f12005-01-25 22:12:55 +00003570 the last occurrence of the String {needle}.
3571 The search is done case-sensitive.
3572 For pattern searches use |match()|.
3573 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaard4755bb2004-09-02 19:12:26 +00003574 If the {needle} is empty the length of {haystack} is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003575 See also |stridx()|. Examples: >
3576 :echo strridx("an angry armadillo", "an") 3
3577<
3578strtrans({expr}) *strtrans()*
3579 The result is a String, which is {expr} with all unprintable
3580 characters translated into printable characters |'isprint'|.
3581 Like they are shown in a window. Example: >
3582 echo strtrans(@a)
3583< This displays a newline in register a as "^@" instead of
3584 starting a new line.
3585
3586submatch({nr}) *submatch()*
3587 Only for an expression in a |:substitute| command. Returns
3588 the {nr}'th submatch of the matched text. When {nr} is 0
3589 the whole matched text is returned.
3590 Example: >
3591 :s/\d\+/\=submatch(0) + 1/
3592< This finds the first number in the line and adds one to it.
3593 A line break is included as a newline character.
3594
3595substitute({expr}, {pat}, {sub}, {flags}) *substitute()*
3596 The result is a String, which is a copy of {expr}, in which
3597 the first match of {pat} is replaced with {sub}. This works
3598 like the ":substitute" command (without any flags). But the
3599 matching with {pat} is always done like the 'magic' option is
3600 set and 'cpoptions' is empty (to make scripts portable).
3601 See |string-match| for how {pat} is used.
3602 And a "~" in {sub} is not replaced with the previous {sub}.
3603 Note that some codes in {sub} have a special meaning
3604 |sub-replace-special|. For example, to replace something with
3605 "\n" (two characters), use "\\\\n" or '\\n'.
3606 When {pat} does not match in {expr}, {expr} is returned
3607 unmodified.
3608 When {flags} is "g", all matches of {pat} in {expr} are
3609 replaced. Otherwise {flags} should be "".
3610 Example: >
3611 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
3612< This removes the last component of the 'path' option. >
3613 :echo substitute("testing", ".*", "\\U\\0", "")
3614< results in "TESTING".
3615
Bram Moolenaar47136d72004-10-12 20:02:24 +00003616synID({lnum}, {col}, {trans}) *synID()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003617 The result is a Number, which is the syntax ID at the position
Bram Moolenaar47136d72004-10-12 20:02:24 +00003618 {lnum} and {col} in the current window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003619 The syntax ID can be used with |synIDattr()| and
3620 |synIDtrans()| to obtain syntax information about text.
Bram Moolenaar47136d72004-10-12 20:02:24 +00003621 {col} is 1 for the leftmost column, {lnum} is 1 for the first
Bram Moolenaar071d4272004-06-13 20:20:40 +00003622 line.
3623 When {trans} is non-zero, transparent items are reduced to the
3624 item that they reveal. This is useful when wanting to know
3625 the effective color. When {trans} is zero, the transparent
3626 item is returned. This is useful when wanting to know which
3627 syntax item is effective (e.g. inside parens).
3628 Warning: This function can be very slow. Best speed is
3629 obtained by going through the file in forward direction.
3630
3631 Example (echoes the name of the syntax item under the cursor): >
3632 :echo synIDattr(synID(line("."), col("."), 1), "name")
3633<
3634synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
3635 The result is a String, which is the {what} attribute of
3636 syntax ID {synID}. This can be used to obtain information
3637 about a syntax item.
3638 {mode} can be "gui", "cterm" or "term", to get the attributes
3639 for that mode. When {mode} is omitted, or an invalid value is
3640 used, the attributes for the currently active highlighting are
3641 used (GUI, cterm or term).
3642 Use synIDtrans() to follow linked highlight groups.
3643 {what} result
3644 "name" the name of the syntax item
3645 "fg" foreground color (GUI: color name used to set
3646 the color, cterm: color number as a string,
3647 term: empty string)
3648 "bg" background color (like "fg")
3649 "fg#" like "fg", but for the GUI and the GUI is
3650 running the name in "#RRGGBB" form
3651 "bg#" like "fg#" for "bg"
3652 "bold" "1" if bold
3653 "italic" "1" if italic
3654 "reverse" "1" if reverse
3655 "inverse" "1" if inverse (= reverse)
3656 "underline" "1" if underlined
3657
3658 Example (echoes the color of the syntax item under the
3659 cursor): >
3660 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
3661<
3662synIDtrans({synID}) *synIDtrans()*
3663 The result is a Number, which is the translated syntax ID of
3664 {synID}. This is the syntax group ID of what is being used to
3665 highlight the character. Highlight links given with
3666 ":highlight link" are followed.
3667
Bram Moolenaarc0197e22004-09-13 20:26:32 +00003668system({expr} [, {input}]) *system()* *E677*
3669 Get the output of the shell command {expr}.
3670 When {input} is given, this string is written to a file and
3671 passed as stdin to the command. The string is written as-is,
3672 you need to take care of using the correct line separators
3673 yourself.
3674 Note: newlines in {expr} may cause the command to fail. The
3675 characters in 'shellquote' and 'shellxquote' may also cause
3676 trouble.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003677 This is not to be used for interactive commands.
3678 The result is a String. Example: >
3679
3680 :let files = system("ls")
3681
3682< To make the result more system-independent, the shell output
3683 is filtered to replace <CR> with <NL> for Macintosh, and
3684 <CR><NL> with <NL> for DOS-like systems.
3685 The command executed is constructed using several options:
3686 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
3687 ({tmp} is an automatically generated file name).
3688 For Unix and OS/2 braces are put around {expr} to allow for
3689 concatenated commands.
3690
3691 The resulting error code can be found in |v:shell_error|.
3692 This function will fail in |restricted-mode|.
3693 Unlike ":!cmd" there is no automatic check for changed files.
3694 Use |:checktime| to force a check.
3695
3696tempname() *tempname()* *temp-file-name*
3697 The result is a String, which is the name of a file that
3698 doesn't exist. It can be used for a temporary file. The name
3699 is different for at least 26 consecutive calls. Example: >
3700 :let tmpfile = tempname()
3701 :exe "redir > " . tmpfile
3702< For Unix, the file will be in a private directory (only
3703 accessible by the current user) to avoid security problems
3704 (e.g., a symlink attack or other people reading your file).
3705 When Vim exits the directory and all files in it are deleted.
3706 For MS-Windows forward slashes are used when the 'shellslash'
3707 option is set or when 'shellcmdflag' starts with '-'.
3708
3709tolower({expr}) *tolower()*
3710 The result is a copy of the String given, with all uppercase
3711 characters turned into lowercase (just like applying |gu| to
3712 the string).
3713
3714toupper({expr}) *toupper()*
3715 The result is a copy of the String given, with all lowercase
3716 characters turned into uppercase (just like applying |gU| to
3717 the string).
3718
Bram Moolenaar8299df92004-07-10 09:47:34 +00003719tr({src}, {fromstr}, {tostr}) *tr()*
3720 The result is a copy of the {src} string with all characters
3721 which appear in {fromstr} replaced by the character in that
3722 position in the {tostr} string. Thus the first character in
3723 {fromstr} is translated into the first character in {tostr}
3724 and so on. Exactly like the unix "tr" command.
3725 This code also deals with multibyte characters properly.
3726
3727 Examples: >
3728 echo tr("hello there", "ht", "HT")
3729< returns "Hello THere" >
3730 echo tr("<blob>", "<>", "{}")
3731< returns "{blob}"
3732
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00003733 *type()*
3734type({expr}) The result is a Number, depending on the type of {expr}:
3735 Number: 0
3736 String: 1
3737 Funcref: 2
3738 List: 3
3739 To avoid the magic numbers it can be used this way: >
3740 :if type(myvar) == type(0)
3741 :if type(myvar) == type("")
3742 :if type(myvar) == type(function("tr"))
3743 :if type(myvar) == type([])
Bram Moolenaar071d4272004-06-13 20:20:40 +00003744
3745virtcol({expr}) *virtcol()*
3746 The result is a Number, which is the screen column of the file
3747 position given with {expr}. That is, the last screen position
3748 occupied by the character at that position, when the screen
3749 would be of unlimited width. When there is a <Tab> at the
3750 position, the returned Number will be the column at the end of
3751 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
3752 set to 8, it returns 8.
3753 For the byte position use |col()|.
3754 When Virtual editing is active in the current mode, a position
3755 beyond the end of the line can be returned. |'virtualedit'|
3756 The accepted positions are:
3757 . the cursor position
3758 $ the end of the cursor line (the result is the
3759 number of displayed characters in the cursor line
3760 plus one)
3761 'x position of mark x (if the mark is not set, 0 is
3762 returned)
3763 Note that only marks in the current file can be used.
3764 Examples: >
3765 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
3766 virtcol("$") with text "foo^Lbar", returns 9
3767 virtcol("'t") with text " there", with 't at 'h', returns 6
3768< The first column is 1. 0 is returned for an error.
3769
3770visualmode([expr]) *visualmode()*
3771 The result is a String, which describes the last Visual mode
3772 used. Initially it returns an empty string, but once Visual
3773 mode has been used, it returns "v", "V", or "<CTRL-V>" (a
3774 single CTRL-V character) for character-wise, line-wise, or
3775 block-wise Visual mode respectively.
3776 Example: >
3777 :exe "normal " . visualmode()
3778< This enters the same Visual mode as before. It is also useful
3779 in scripts if you wish to act differently depending on the
3780 Visual mode that was used.
3781
3782 If an expression is supplied that results in a non-zero number
3783 or a non-empty string, then the Visual mode will be cleared
3784 and the old value is returned. Note that " " and "0" are also
3785 non-empty strings, thus cause the mode to be cleared.
3786
3787 *winbufnr()*
3788winbufnr({nr}) The result is a Number, which is the number of the buffer
3789 associated with window {nr}. When {nr} is zero, the number of
3790 the buffer in the current window is returned. When window
3791 {nr} doesn't exist, -1 is returned.
3792 Example: >
3793 :echo "The file in the current window is " . bufname(winbufnr(0))
3794<
3795 *wincol()*
3796wincol() The result is a Number, which is the virtual column of the
3797 cursor in the window. This is counting screen cells from the
3798 left side of the window. The leftmost column is one.
3799
3800winheight({nr}) *winheight()*
3801 The result is a Number, which is the height of window {nr}.
3802 When {nr} is zero, the height of the current window is
3803 returned. When window {nr} doesn't exist, -1 is returned.
3804 An existing window always has a height of zero or more.
3805 Examples: >
3806 :echo "The current window has " . winheight(0) . " lines."
3807<
3808 *winline()*
3809winline() The result is a Number, which is the screen line of the cursor
3810 in the window. This is counting screen lines from the top of
3811 the window. The first line is one.
3812
3813 *winnr()*
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00003814winnr([{arg}]) The result is a Number, which is the number of the current
3815 window. The top window has number 1.
3816 When the optional argument is "$", the number of the
3817 last window is returnd (the window count).
3818 When the optional argument is "#", the number of the last
3819 accessed window is returned (where |CTRL-W_p| goes to).
3820 If there is no previous window 0 is returned.
3821 The number can be used with |CTRL-W_w| and ":wincmd w"
3822 |:wincmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003823
3824 *winrestcmd()*
3825winrestcmd() Returns a sequence of |:resize| commands that should restore
3826 the current window sizes. Only works properly when no windows
3827 are opened or closed and the current window is unchanged.
3828 Example: >
3829 :let cmd = winrestcmd()
3830 :call MessWithWindowSizes()
3831 :exe cmd
3832
3833winwidth({nr}) *winwidth()*
3834 The result is a Number, which is the width of window {nr}.
3835 When {nr} is zero, the width of the current window is
3836 returned. When window {nr} doesn't exist, -1 is returned.
3837 An existing window always has a width of zero or more.
3838 Examples: >
3839 :echo "The current window has " . winwidth(0) . " columns."
3840 :if winwidth(0) <= 50
3841 : exe "normal 50\<C-W>|"
3842 :endif
3843<
3844
3845 *feature-list*
3846There are three types of features:
38471. Features that are only supported when they have been enabled when Vim
3848 was compiled |+feature-list|. Example: >
3849 :if has("cindent")
38502. Features that are only supported when certain conditions have been met.
3851 Example: >
3852 :if has("gui_running")
3853< *has-patch*
38543. Included patches. First check |v:version| for the version of Vim.
3855 Then the "patch123" feature means that patch 123 has been included for
3856 this version. Example (checking version 6.2.148 or later): >
3857 :if v:version > 602 || v:version == 602 && has("patch148")
3858
3859all_builtin_terms Compiled with all builtin terminals enabled.
3860amiga Amiga version of Vim.
3861arabic Compiled with Arabic support |Arabic|.
3862arp Compiled with ARP support (Amiga).
3863autocmd Compiled with autocommands support.
3864balloon_eval Compiled with |balloon-eval| support.
3865beos BeOS version of Vim.
3866browse Compiled with |:browse| support, and browse() will
3867 work.
3868builtin_terms Compiled with some builtin terminals.
3869byte_offset Compiled with support for 'o' in 'statusline'
3870cindent Compiled with 'cindent' support.
3871clientserver Compiled with remote invocation support |clientserver|.
3872clipboard Compiled with 'clipboard' support.
3873cmdline_compl Compiled with |cmdline-completion| support.
3874cmdline_hist Compiled with |cmdline-history| support.
3875cmdline_info Compiled with 'showcmd' and 'ruler' support.
3876comments Compiled with |'comments'| support.
3877cryptv Compiled with encryption support |encryption|.
3878cscope Compiled with |cscope| support.
3879compatible Compiled to be very Vi compatible.
3880debug Compiled with "DEBUG" defined.
3881dialog_con Compiled with console dialog support.
3882dialog_gui Compiled with GUI dialog support.
3883diff Compiled with |vimdiff| and 'diff' support.
3884digraphs Compiled with support for digraphs.
3885dnd Compiled with support for the "~ register |quote_~|.
3886dos32 32 bits DOS (DJGPP) version of Vim.
3887dos16 16 bits DOS version of Vim.
3888ebcdic Compiled on a machine with ebcdic character set.
3889emacs_tags Compiled with support for Emacs tags.
3890eval Compiled with expression evaluation support. Always
3891 true, of course!
3892ex_extra Compiled with extra Ex commands |+ex_extra|.
3893extra_search Compiled with support for |'incsearch'| and
3894 |'hlsearch'|
3895farsi Compiled with Farsi support |farsi|.
3896file_in_path Compiled with support for |gf| and |<cfile>|
3897find_in_path Compiled with support for include file searches
3898 |+find_in_path|.
3899fname_case Case in file names matters (for Amiga, MS-DOS, and
3900 Windows this is not present).
3901folding Compiled with |folding| support.
3902footer Compiled with GUI footer support. |gui-footer|
3903fork Compiled to use fork()/exec() instead of system().
3904gettext Compiled with message translation |multi-lang|
3905gui Compiled with GUI enabled.
3906gui_athena Compiled with Athena GUI.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003907gui_beos Compiled with BeOS GUI.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003908gui_gtk Compiled with GTK+ GUI (any version).
3909gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
Bram Moolenaar843ee412004-06-30 16:16:41 +00003910gui_kde Compiled with KDE GUI |KVim|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003911gui_mac Compiled with Macintosh GUI.
3912gui_motif Compiled with Motif GUI.
3913gui_photon Compiled with Photon GUI.
3914gui_win32 Compiled with MS Windows Win32 GUI.
3915gui_win32s idem, and Win32s system being used (Windows 3.1)
3916gui_running Vim is running in the GUI, or it will start soon.
3917hangul_input Compiled with Hangul input support. |hangul|
3918iconv Can use iconv() for conversion.
3919insert_expand Compiled with support for CTRL-X expansion commands in
3920 Insert mode.
3921jumplist Compiled with |jumplist| support.
3922keymap Compiled with 'keymap' support.
3923langmap Compiled with 'langmap' support.
3924libcall Compiled with |libcall()| support.
3925linebreak Compiled with 'linebreak', 'breakat' and 'showbreak'
3926 support.
3927lispindent Compiled with support for lisp indenting.
3928listcmds Compiled with commands for the buffer list |:files|
3929 and the argument list |arglist|.
3930localmap Compiled with local mappings and abbr. |:map-local|
3931mac Macintosh version of Vim.
3932macunix Macintosh version of Vim, using Unix files (OS-X).
3933menu Compiled with support for |:menu|.
3934mksession Compiled with support for |:mksession|.
3935modify_fname Compiled with file name modifiers. |filename-modifiers|
3936mouse Compiled with support mouse.
3937mouseshape Compiled with support for 'mouseshape'.
3938mouse_dec Compiled with support for Dec terminal mouse.
3939mouse_gpm Compiled with support for gpm (Linux console mouse)
3940mouse_netterm Compiled with support for netterm mouse.
3941mouse_pterm Compiled with support for qnx pterm mouse.
3942mouse_xterm Compiled with support for xterm mouse.
3943multi_byte Compiled with support for editing Korean et al.
3944multi_byte_ime Compiled with support for IME input method.
3945multi_lang Compiled with support for multiple languages.
Bram Moolenaar325b7a22004-07-05 15:58:32 +00003946mzscheme Compiled with MzScheme interface |mzscheme|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003947netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaar009b2592004-10-24 19:18:58 +00003948netbeans_enabled Compiled with support for |netbeans| and it's used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003949ole Compiled with OLE automation support for Win32.
3950os2 OS/2 version of Vim.
3951osfiletype Compiled with support for osfiletypes |+osfiletype|
3952path_extra Compiled with up/downwards search in 'path' and 'tags'
3953perl Compiled with Perl interface.
3954postscript Compiled with PostScript file printing.
3955printer Compiled with |:hardcopy| support.
3956python Compiled with Python interface.
3957qnx QNX version of Vim.
3958quickfix Compiled with |quickfix| support.
3959rightleft Compiled with 'rightleft' support.
3960ruby Compiled with Ruby interface |ruby|.
3961scrollbind Compiled with 'scrollbind' support.
3962showcmd Compiled with 'showcmd' support.
3963signs Compiled with |:sign| support.
3964smartindent Compiled with 'smartindent' support.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003965sniff Compiled with SNiFF interface support.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003966statusline Compiled with support for 'statusline', 'rulerformat'
3967 and special formats of 'titlestring' and 'iconstring'.
3968sun_workshop Compiled with support for Sun |workshop|.
3969syntax Compiled with syntax highlighting support.
3970syntax_items There are active syntax highlighting items for the
3971 current buffer.
3972system Compiled to use system() instead of fork()/exec().
3973tag_binary Compiled with binary searching in tags files
3974 |tag-binary-search|.
3975tag_old_static Compiled with support for old static tags
3976 |tag-old-static|.
3977tag_any_white Compiled with support for any white characters in tags
3978 files |tag-any-white|.
3979tcl Compiled with Tcl interface.
3980terminfo Compiled with terminfo instead of termcap.
3981termresponse Compiled with support for |t_RV| and |v:termresponse|.
3982textobjects Compiled with support for |text-objects|.
3983tgetent Compiled with tgetent support, able to use a termcap
3984 or terminfo file.
3985title Compiled with window title support |'title'|.
3986toolbar Compiled with support for |gui-toolbar|.
3987unix Unix version of Vim.
3988user_commands User-defined commands.
3989viminfo Compiled with viminfo support.
3990vim_starting True while initial source'ing takes place.
3991vertsplit Compiled with vertically split windows |:vsplit|.
3992virtualedit Compiled with 'virtualedit' option.
3993visual Compiled with Visual mode.
3994visualextra Compiled with extra Visual mode commands.
3995 |blockwise-operators|.
3996vms VMS version of Vim.
3997vreplace Compiled with |gR| and |gr| commands.
3998wildignore Compiled with 'wildignore' option.
3999wildmenu Compiled with 'wildmenu' option.
4000windows Compiled with support for more than one window.
4001winaltkeys Compiled with 'winaltkeys' option.
4002win16 Win16 version of Vim (MS-Windows 3.1).
4003win32 Win32 version of Vim (MS-Windows 95/98/ME/NT/2000/XP).
4004win64 Win64 version of Vim (MS-Windows 64 bit).
4005win32unix Win32 version of Vim, using Unix files (Cygwin)
4006win95 Win32 version for MS-Windows 95/98/ME.
4007writebackup Compiled with 'writebackup' default on.
4008xfontset Compiled with X fontset support |xfontset|.
4009xim Compiled with X input method support |xim|.
4010xsmp Compiled with X session management support.
4011xsmp_interact Compiled with interactive X session management support.
4012xterm_clipboard Compiled with support for xterm clipboard.
4013xterm_save Compiled with support for saving and restoring the
4014 xterm screen.
4015x11 Compiled with X11 support.
4016
4017 *string-match*
4018Matching a pattern in a String
4019
4020A regexp pattern as explained at |pattern| is normally used to find a match in
4021the buffer lines. When a pattern is used to find a match in a String, almost
4022everything works in the same way. The difference is that a String is handled
4023like it is one line. When it contains a "\n" character, this is not seen as a
4024line break for the pattern. It can be matched with a "\n" in the pattern, or
4025with ".". Example: >
4026 :let a = "aaaa\nxxxx"
4027 :echo matchstr(a, "..\n..")
4028 aa
4029 xx
4030 :echo matchstr(a, "a.x")
4031 a
4032 x
4033
4034Don't forget that "^" will only match at the first character of the String and
4035"$" at the last character of the string. They don't match after or before a
4036"\n".
4037
4038==============================================================================
40395. Defining functions *user-functions*
4040
4041New functions can be defined. These can be called just like builtin
4042functions. The function executes a sequence of Ex commands. Normal mode
4043commands can be executed with the |:normal| command.
4044
4045The function name must start with an uppercase letter, to avoid confusion with
4046builtin functions. To prevent from using the same name in different scripts
4047avoid obvious, short names. A good habit is to start the function name with
4048the name of the script, e.g., "HTMLcolor()".
4049
4050It's also possible to use curly braces, see |curly-braces-names|.
4051
4052 *local-function*
4053A function local to a script must start with "s:". A local script function
4054can only be called from within the script and from functions, user commands
4055and autocommands defined in the script. It is also possible to call the
4056function from a mappings defined in the script, but then |<SID>| must be used
4057instead of "s:" when the mapping is expanded outside of the script.
4058
4059 *:fu* *:function* *E128* *E129* *E123*
4060:fu[nction] List all functions and their arguments.
4061
4062:fu[nction] {name} List function {name}.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004063 {name} can also be a Dictionary entry that is a
4064 Funcref: >
4065 :function dict.init
4066< *E124* *E125*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004067:fu[nction][!] {name}([arguments]) [range] [abort] [dict]
Bram Moolenaar071d4272004-06-13 20:20:40 +00004068 Define a new function by the name {name}. The name
4069 must be made of alphanumeric characters and '_', and
4070 must start with a capital or "s:" (see above).
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004071
4072 {name} can also be a Dictionary entry that is a
4073 Funcref: >
4074 :function dict.init(arg)
4075< "dict" must be an existing dictionary. The entry
4076 "init" is added if it didn't exist yet. Otherwise [!]
4077 is required to overwrite an existing function. The
4078 result is a |Funcref| to a numbered function. The
4079 function can only be used with a |Funcref| and will be
4080 deleted if there are no more references to it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004081 *E127* *E122*
4082 When a function by this name already exists and [!] is
4083 not used an error message is given. When [!] is used,
4084 an existing function is silently replaced. Unless it
4085 is currently being executed, that is an error.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00004086
4087 For the {arguments} see |function-argument|.
4088
Bram Moolenaar071d4272004-06-13 20:20:40 +00004089 *a:firstline* *a:lastline*
4090 When the [range] argument is added, the function is
4091 expected to take care of a range itself. The range is
4092 passed as "a:firstline" and "a:lastline". If [range]
4093 is excluded, ":{range}call" will call the function for
4094 each line in the range, with the cursor on the start
4095 of each line. See |function-range-example|.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004096
Bram Moolenaar071d4272004-06-13 20:20:40 +00004097 When the [abort] argument is added, the function will
4098 abort as soon as an error is detected.
4099 The last used search pattern and the redo command "."
4100 will not be changed by the function.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004101
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004102 When the [dict] argument is added, the function must
4103 be invoked through an entry in a Dictionary. The
4104 local variable "self" will then be set to the
4105 dictionary. See |Dictionary-function|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004106
4107 *:endf* *:endfunction* *E126* *E193*
4108:endf[unction] The end of a function definition. Must be on a line
4109 by its own, without other commands.
4110
4111 *:delf* *:delfunction* *E130* *E131*
4112:delf[unction] {name} Delete function {name}.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004113 {name} can also be a Dictionary entry that is a
4114 Funcref: >
4115 :delfunc dict.init
4116< This will remove the "init" entry from "dict". The
4117 function is deleted if there are no more references to
4118 it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004119 *:retu* *:return* *E133*
4120:retu[rn] [expr] Return from a function. When "[expr]" is given, it is
4121 evaluated and returned as the result of the function.
4122 If "[expr]" is not given, the number 0 is returned.
4123 When a function ends without an explicit ":return",
4124 the number 0 is returned.
4125 Note that there is no check for unreachable lines,
4126 thus there is no warning if commands follow ":return".
4127
4128 If the ":return" is used after a |:try| but before the
4129 matching |:finally| (if present), the commands
4130 following the ":finally" up to the matching |:endtry|
4131 are executed first. This process applies to all
4132 nested ":try"s inside the function. The function
4133 returns at the outermost ":endtry".
4134
Bram Moolenaar8f999f12005-01-25 22:12:55 +00004135 *function-argument* *a:var*
4136An argument can be defined by giving its name. In the function this can then
4137be used as "a:name" ("a:" for argument).
4138 *a:0* *a:1* *a:000* *E740*
4139Up to 20 arguments can be given, separated by commas. After the named
4140arguments an argument "..." can be specified, which means that more arguments
4141may optionally be following. In the function the extra arguments can be used
4142as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which
4143can be 0). "a:000" is set to a List that contains these arguments.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004144
Bram Moolenaar8f999f12005-01-25 22:12:55 +00004145When not using "...", the number of arguments in a function call must be equal
4146to the number of named arguments. When using "...", the number of arguments
4147may be larger.
4148
4149It is also possible to define a function without any arguments. You must
4150still supply the () then. The body of the function follows in the next lines,
4151until the matching |:endfunction|. It is allowed to define another function
4152inside a function body.
4153
4154 *local-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004155Inside a function variables can be used. These are local variables, which
4156will disappear when the function returns. Global variables need to be
4157accessed with "g:".
4158
4159Example: >
4160 :function Table(title, ...)
4161 : echohl Title
4162 : echo a:title
4163 : echohl None
4164 : let idx = 1
4165 : while idx <= a:0
4166 : echo a:{idx} . ' '
4167 : let idx = idx + 1
4168 : endwhile
4169 : return idx
4170 :endfunction
4171
4172This function can then be called with: >
4173 let lines = Table("Table", "line1", "line2")
4174 let lines = Table("Empty Table")
4175
4176To return more than one value, pass the name of a global variable: >
4177 :function Compute(n1, n2, divname)
4178 : if a:n2 == 0
4179 : return "fail"
4180 : endif
4181 : let g:{a:divname} = a:n1 / a:n2
4182 : return "ok"
4183 :endfunction
4184
4185This function can then be called with: >
4186 :let success = Compute(13, 1324, "div")
4187 :if success == "ok"
4188 : echo div
4189 :endif
4190
4191An alternative is to return a command that can be executed. This also works
4192with local variables in a calling function. Example: >
4193 :function Foo()
4194 : execute Bar()
4195 : echo "line " . lnum . " column " . col
4196 :endfunction
4197
4198 :function Bar()
4199 : return "let lnum = " . line(".") . " | let col = " . col(".")
4200 :endfunction
4201
4202The names "lnum" and "col" could also be passed as argument to Bar(), to allow
4203the caller to set the names.
4204
4205 *:cal* *:call* *E107*
4206:[range]cal[l] {name}([arguments])
4207 Call a function. The name of the function and its arguments
4208 are as specified with |:function|. Up to 20 arguments can be
4209 used.
4210 Without a range and for functions that accept a range, the
4211 function is called once. When a range is given the cursor is
4212 positioned at the start of the first line before executing the
4213 function.
4214 When a range is given and the function doesn't handle it
4215 itself, the function is executed for each line in the range,
4216 with the cursor in the first column of that line. The cursor
4217 is left at the last line (possibly moved by the last function
4218 call). The arguments are re-evaluated for each line. Thus
4219 this works:
4220 *function-range-example* >
4221 :function Mynumber(arg)
4222 : echo line(".") . " " . a:arg
4223 :endfunction
4224 :1,5call Mynumber(getline("."))
4225<
4226 The "a:firstline" and "a:lastline" are defined anyway, they
4227 can be used to do something different at the start or end of
4228 the range.
4229
4230 Example of a function that handles the range itself: >
4231
4232 :function Cont() range
4233 : execute (a:firstline + 1) . "," . a:lastline . 's/^/\t\\ '
4234 :endfunction
4235 :4,8call Cont()
4236<
4237 This function inserts the continuation character "\" in front
4238 of all the lines in the range, except the first one.
4239
4240 *E132*
4241The recursiveness of user functions is restricted with the |'maxfuncdepth'|
4242option.
4243
4244 *autoload-functions*
4245When using many or large functions, it's possible to automatically define them
4246only when they are used. Use the FuncUndefined autocommand event with a
4247pattern that matches the function(s) to be defined. Example: >
4248
4249 :au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
4250
4251The file "~/vim/bufnetfuncs.vim" should then define functions that start with
4252"BufNet". Also see |FuncUndefined|.
4253
4254==============================================================================
42556. Curly braces names *curly-braces-names*
4256
4257Wherever you can use a variable, you can use a "curly braces name" variable.
4258This is a regular variable name with one or more expressions wrapped in braces
4259{} like this: >
4260 my_{adjective}_variable
4261
4262When Vim encounters this, it evaluates the expression inside the braces, puts
4263that in place of the expression, and re-interprets the whole as a variable
4264name. So in the above example, if the variable "adjective" was set to
4265"noisy", then the reference would be to "my_noisy_variable", whereas if
4266"adjective" was set to "quiet", then it would be to "my_quiet_variable".
4267
4268One application for this is to create a set of variables governed by an option
4269value. For example, the statement >
4270 echo my_{&background}_message
4271
4272would output the contents of "my_dark_message" or "my_light_message" depending
4273on the current value of 'background'.
4274
4275You can use multiple brace pairs: >
4276 echo my_{adverb}_{adjective}_message
4277..or even nest them: >
4278 echo my_{ad{end_of_word}}_message
4279where "end_of_word" is either "verb" or "jective".
4280
4281However, the expression inside the braces must evaluate to a valid single
4282variable name. e.g. this is invalid: >
4283 :let foo='a + b'
4284 :echo c{foo}d
4285.. since the result of expansion is "ca + bd", which is not a variable name.
4286
4287 *curly-braces-function-names*
4288You can call and define functions by an evaluated name in a similar way.
4289Example: >
4290 :let func_end='whizz'
4291 :call my_func_{func_end}(parameter)
4292
4293This would call the function "my_func_whizz(parameter)".
4294
4295==============================================================================
42967. Commands *expression-commands*
4297
4298:let {var-name} = {expr1} *:let* *E18*
4299 Set internal variable {var-name} to the result of the
4300 expression {expr1}. The variable will get the type
4301 from the {expr}. If {var-name} didn't exist yet, it
4302 is created.
4303
Bram Moolenaar13065c42005-01-08 16:08:21 +00004304:let {var-name}[{idx}] = {expr1} *E689*
4305 Set a list item to the result of the expression
4306 {expr1}. {var-name} must refer to a list and {idx}
4307 must be a valid index in that list. For nested list
4308 the index can be repeated.
4309 This cannot be used to add an item to a list.
4310
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004311 *E711* *E719*
4312:let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710*
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004313 Set a sequence of items in a List to the result of the
4314 expression {expr1}, which must be a list with the
4315 correct number of items.
4316 {idx1} can be omitted, zero is used instead.
4317 {idx2} can be omitted, meaning the end of the list.
4318 When the selected range of items is partly past the
4319 end of the list, items will be added.
4320
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00004321 *:let+=* *:let-=* *:let.=*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004322:let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
4323:let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
4324:let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
4325 These fail if {var} was not set yet and when the type
4326 of {var} and {expr1} don't fit the operator.
4327
4328
Bram Moolenaar071d4272004-06-13 20:20:40 +00004329:let ${env-name} = {expr1} *:let-environment* *:let-$*
4330 Set environment variable {env-name} to the result of
4331 the expression {expr1}. The type is always String.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004332:let ${env-name} .= {expr1}
4333 Append {expr1} to the environment variable {env-name}.
4334 If the environment variable didn't exist yet this
4335 works like "=".
Bram Moolenaar071d4272004-06-13 20:20:40 +00004336
4337:let @{reg-name} = {expr1} *:let-register* *:let-@*
4338 Write the result of the expression {expr1} in register
4339 {reg-name}. {reg-name} must be a single letter, and
4340 must be the name of a writable register (see
4341 |registers|). "@@" can be used for the unnamed
4342 register, "@/" for the search pattern.
4343 If the result of {expr1} ends in a <CR> or <NL>, the
4344 register will be linewise, otherwise it will be set to
4345 characterwise.
4346 This can be used to clear the last search pattern: >
4347 :let @/ = ""
4348< This is different from searching for an empty string,
4349 that would match everywhere.
4350
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004351:let @{reg-name} .= {expr1}
4352 Append {expr1} to register {reg-name}. If the
4353 register was empty it's like setting it to {expr1}.
4354
Bram Moolenaar071d4272004-06-13 20:20:40 +00004355:let &{option-name} = {expr1} *:let-option* *:let-star*
4356 Set option {option-name} to the result of the
Bram Moolenaarfca34d62005-01-04 21:38:36 +00004357 expression {expr1}. A String or Number value is
4358 always converted to the type of the option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004359 For an option local to a window or buffer the effect
4360 is just like using the |:set| command: both the local
4361 value and the global value is changed.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00004362 Example: >
4363 :let &path = &path . ',/usr/local/include'
Bram Moolenaar071d4272004-06-13 20:20:40 +00004364
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004365:let &{option-name} .= {expr1}
4366 For a string option: Append {expr1} to the value.
4367 Does not insert a comma like |:set+=|.
4368
4369:let &{option-name} += {expr1}
4370:let &{option-name} -= {expr1}
4371 For a number or boolean option: Add or subtract
4372 {expr1}.
4373
Bram Moolenaar071d4272004-06-13 20:20:40 +00004374:let &l:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004375:let &l:{option-name} .= {expr1}
4376:let &l:{option-name} += {expr1}
4377:let &l:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00004378 Like above, but only set the local value of an option
4379 (if there is one). Works like |:setlocal|.
4380
4381:let &g:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004382:let &g:{option-name} .= {expr1}
4383:let &g:{option-name} += {expr1}
4384:let &g:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00004385 Like above, but only set the global value of an option
4386 (if there is one). Works like |:setglobal|.
4387
Bram Moolenaar13065c42005-01-08 16:08:21 +00004388:let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
Bram Moolenaarfca34d62005-01-04 21:38:36 +00004389 {expr1} must evaluate to a List. The first item in
4390 the list is assigned to {name1}, the second item to
4391 {name2}, etc.
4392 The number of names must match the number of items in
4393 the List.
4394 Each name can be one of the items of the ":let"
4395 command as mentioned above.
4396 Example: >
4397 :let [s, item] = GetItem(s)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004398< Detail: {expr1} is evaluated first, then the
4399 assignments are done in sequence. This matters if
4400 {name2} depends on {name1}. Example: >
4401 :let x = [0, 1]
4402 :let i = 0
4403 :let [i, x[i]] = [1, 2]
4404 :echo x
4405< The result is [0, 2].
4406
4407:let [{name1}, {name2}, ...] .= {expr1}
4408:let [{name1}, {name2}, ...] += {expr1}
4409:let [{name1}, {name2}, ...] -= {expr1}
4410 Like above, but append/add/subtract the value for each
4411 List item.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00004412
4413:let [{name}, ..., ; {lastname}] = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004414 Like |let-unpack| above, but the List may have more
4415 items than there are names. A list of the remaining
4416 items is assigned to {lastname}. If there are no
4417 remaining items {lastname} is set to an empty list.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00004418 Example: >
4419 :let [a, b; rest] = ["aval", "bval", 3, 4]
4420<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004421:let [{name}, ..., ; {lastname}] .= {expr1}
4422:let [{name}, ..., ; {lastname}] += {expr1}
4423:let [{name}, ..., ; {lastname}] -= {expr1}
4424 Like above, but append/add/subtract the value for each
4425 List item.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004426 *E106*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004427:let {var-name} .. List the value of variable {var-name}. Multiple
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00004428 variable names may be given. Special names recognized
4429 here: *E738*
4430 g: global variables.
4431 b: local buffer variables.
4432 w: local window variables.
4433 v: Vim variables.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004434
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004435:let List the values of all variables. The type of the
4436 variable is indicated before the value:
4437 <nothing> String
4438 # Number
4439 * Funcref
Bram Moolenaar071d4272004-06-13 20:20:40 +00004440
4441 *:unlet* *:unl* *E108*
4442:unl[et][!] {var-name} ...
4443 Remove the internal variable {var-name}. Several
4444 variable names can be given, they are all removed.
4445 With [!] no error message is given for non-existing
4446 variables.
Bram Moolenaar9cd15162005-01-16 22:02:49 +00004447 One or more items from a List can be removed: >
4448 :unlet list[3] " remove fourth item
4449 :unlet list[3:] " remove fourth item to last
4450< One item from a Dictionary can be removed at a time: >
4451 :unlet dict['two']
4452 :unlet dict.two
Bram Moolenaar071d4272004-06-13 20:20:40 +00004453
4454:if {expr1} *:if* *:endif* *:en* *E171* *E579* *E580*
4455:en[dif] Execute the commands until the next matching ":else"
4456 or ":endif" if {expr1} evaluates to non-zero.
4457
4458 From Vim version 4.5 until 5.0, every Ex command in
4459 between the ":if" and ":endif" is ignored. These two
4460 commands were just to allow for future expansions in a
4461 backwards compatible way. Nesting was allowed. Note
4462 that any ":else" or ":elseif" was ignored, the "else"
4463 part was not executed either.
4464
4465 You can use this to remain compatible with older
4466 versions: >
4467 :if version >= 500
4468 : version-5-specific-commands
4469 :endif
4470< The commands still need to be parsed to find the
4471 "endif". Sometimes an older Vim has a problem with a
4472 new command. For example, ":silent" is recognized as
4473 a ":substitute" command. In that case ":execute" can
4474 avoid problems: >
4475 :if version >= 600
4476 : execute "silent 1,$delete"
4477 :endif
4478<
4479 NOTE: The ":append" and ":insert" commands don't work
4480 properly in between ":if" and ":endif".
4481
4482 *:else* *:el* *E581* *E583*
4483:el[se] Execute the commands until the next matching ":else"
4484 or ":endif" if they previously were not being
4485 executed.
4486
4487 *:elseif* *:elsei* *E582* *E584*
4488:elsei[f] {expr1} Short for ":else" ":if", with the addition that there
4489 is no extra ":endif".
4490
4491:wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004492 *E170* *E585* *E588* *E733*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004493:endw[hile] Repeat the commands between ":while" and ":endwhile",
4494 as long as {expr1} evaluates to non-zero.
4495 When an error is detected from a command inside the
4496 loop, execution continues after the "endwhile".
Bram Moolenaar12805862005-01-05 22:16:17 +00004497 Example: >
4498 :let lnum = 1
4499 :while lnum <= line("$")
4500 :call FixLine(lnum)
4501 :let lnum = lnum + 1
4502 :endwhile
4503<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004504 NOTE: The ":append" and ":insert" commands don't work
Bram Moolenaard8b02732005-01-14 21:48:43 +00004505 properly inside a ":while" and ":for" loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004506
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00004507:for {var} in {list} *:for* *E690* *E732*
Bram Moolenaar12805862005-01-05 22:16:17 +00004508:endfo[r] *:endfo* *:endfor*
4509 Repeat the commands between ":for" and ":endfor" for
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004510 each item in {list}. variable {var} is set to the
4511 value of each item.
4512 When an error is detected for a command inside the
Bram Moolenaar12805862005-01-05 22:16:17 +00004513 loop, execution continues after the "endfor".
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004514 Changing {list} affects what items are used. Make a
4515 copy if this is unwanted: >
4516 :for item in copy(mylist)
4517< When not making a copy, Vim stores a reference to the
4518 next item in the list, before executing the commands
4519 with the current item. Thus the current item can be
4520 removed without effect. Removing any later item means
4521 it will not be found. Thus the following example
4522 works (an inefficient way to make a list empty): >
4523 :for item in mylist
Bram Moolenaar12805862005-01-05 22:16:17 +00004524 :call remove(mylist, 0)
4525 :endfor
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00004526< Note that reordering the list (e.g., with sort() or
4527 reverse()) may have unexpected effects.
4528 Note that the type of each list item should be
Bram Moolenaar12805862005-01-05 22:16:17 +00004529 identical to avoid errors for the type of {var}
4530 changing. Unlet the variable at the end of the loop
4531 to allow multiple item types.
4532
4533:for {var} in {string}
4534:endfo[r] Like ":for" above, but use each character in {string}
4535 as a list item.
4536 Composing characters are used as separate characters.
4537 A Number is first converted to a String.
4538
4539:for [{var1}, {var2}, ...] in {listlist}
4540:endfo[r]
4541 Like ":for" above, but each item in {listlist} must be
4542 a list, of which each item is assigned to {var1},
4543 {var2}, etc. Example: >
4544 :for [lnum, col] in [[1, 3], [2, 5], [3, 8]]
4545 :echo getline(lnum)[col]
4546 :endfor
4547<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004548 *:continue* *:con* *E586*
Bram Moolenaar12805862005-01-05 22:16:17 +00004549:con[tinue] When used inside a ":while" or ":for" loop, jumps back
4550 to the start of the loop.
4551 If it is used after a |:try| inside the loop but
4552 before the matching |:finally| (if present), the
4553 commands following the ":finally" up to the matching
4554 |:endtry| are executed first. This process applies to
4555 all nested ":try"s inside the loop. The outermost
4556 ":endtry" then jumps back to the start of the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004557
4558 *:break* *:brea* *E587*
Bram Moolenaar12805862005-01-05 22:16:17 +00004559:brea[k] When used inside a ":while" or ":for" loop, skips to
4560 the command after the matching ":endwhile" or
4561 ":endfor".
4562 If it is used after a |:try| inside the loop but
4563 before the matching |:finally| (if present), the
4564 commands following the ":finally" up to the matching
4565 |:endtry| are executed first. This process applies to
4566 all nested ":try"s inside the loop. The outermost
4567 ":endtry" then jumps to the command after the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004568
4569:try *:try* *:endt* *:endtry* *E600* *E601* *E602*
4570:endt[ry] Change the error handling for the commands between
4571 ":try" and ":endtry" including everything being
4572 executed across ":source" commands, function calls,
4573 or autocommand invocations.
4574
4575 When an error or interrupt is detected and there is
4576 a |:finally| command following, execution continues
4577 after the ":finally". Otherwise, or when the
4578 ":endtry" is reached thereafter, the next
4579 (dynamically) surrounding ":try" is checked for
4580 a corresponding ":finally" etc. Then the script
4581 processing is terminated. (Whether a function
4582 definition has an "abort" argument does not matter.)
4583 Example: >
4584 :try | edit too much | finally | echo "cleanup" | endtry
4585 :echo "impossible" " not reached, script terminated above
4586<
4587 Moreover, an error or interrupt (dynamically) inside
4588 ":try" and ":endtry" is converted to an exception. It
4589 can be caught as if it were thrown by a |:throw|
4590 command (see |:catch|). In this case, the script
4591 processing is not terminated.
4592
4593 The value "Vim:Interrupt" is used for an interrupt
4594 exception. An error in a Vim command is converted
4595 to a value of the form "Vim({command}):{errmsg}",
4596 other errors are converted to a value of the form
4597 "Vim:{errmsg}". {command} is the full command name,
4598 and {errmsg} is the message that is displayed if the
4599 error exception is not caught, always beginning with
4600 the error number.
4601 Examples: >
4602 :try | sleep 100 | catch /^Vim:Interrupt$/ | endtry
4603 :try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry
4604<
4605 *:cat* *:catch* *E603* *E604* *E605*
4606:cat[ch] /{pattern}/ The following commands until the next ":catch",
4607 |:finally|, or |:endtry| that belongs to the same
4608 |:try| as the ":catch" are executed when an exception
4609 matching {pattern} is being thrown and has not yet
4610 been caught by a previous ":catch". Otherwise, these
4611 commands are skipped.
4612 When {pattern} is omitted all errors are caught.
4613 Examples: >
4614 :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C)
4615 :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors
4616 :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts
4617 :catch /^Vim(write):/ " catch all errors in :write
4618 :catch /^Vim\%((\a\+)\)\=:E123/ " catch error E123
4619 :catch /my-exception/ " catch user exception
4620 :catch /.*/ " catch everything
4621 :catch " same as /.*/
4622<
4623 Another character can be used instead of / around the
4624 {pattern}, so long as it does not have a special
4625 meaning (e.g., '|' or '"') and doesn't occur inside
4626 {pattern}.
4627 NOTE: It is not reliable to ":catch" the TEXT of
4628 an error message because it may vary in different
4629 locales.
4630
4631 *:fina* *:finally* *E606* *E607*
4632:fina[lly] The following commands until the matching |:endtry|
4633 are executed whenever the part between the matching
4634 |:try| and the ":finally" is left: either by falling
4635 through to the ":finally" or by a |:continue|,
4636 |:break|, |:finish|, or |:return|, or by an error or
4637 interrupt or exception (see |:throw|).
4638
4639 *:th* *:throw* *E608*
4640:th[row] {expr1} The {expr1} is evaluated and thrown as an exception.
4641 If the ":throw" is used after a |:try| but before the
4642 first corresponding |:catch|, commands are skipped
4643 until the first ":catch" matching {expr1} is reached.
4644 If there is no such ":catch" or if the ":throw" is
4645 used after a ":catch" but before the |:finally|, the
4646 commands following the ":finally" (if present) up to
4647 the matching |:endtry| are executed. If the ":throw"
4648 is after the ":finally", commands up to the ":endtry"
4649 are skipped. At the ":endtry", this process applies
4650 again for the next dynamically surrounding ":try"
4651 (which may be found in a calling function or sourcing
4652 script), until a matching ":catch" has been found.
4653 If the exception is not caught, the command processing
4654 is terminated.
4655 Example: >
4656 :try | throw "oops" | catch /^oo/ | echo "caught" | endtry
4657<
4658
4659 *:ec* *:echo*
4660:ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The
4661 first {expr1} starts on a new line.
4662 Also see |:comment|.
4663 Use "\n" to start a new line. Use "\r" to move the
4664 cursor to the first column.
4665 Uses the highlighting set by the |:echohl| command.
4666 Cannot be followed by a comment.
4667 Example: >
4668 :echo "the value of 'shell' is" &shell
4669< A later redraw may make the message disappear again.
4670 To avoid that a command from before the ":echo" causes
4671 a redraw afterwards (redraws are often postponed until
4672 you type something), force a redraw with the |:redraw|
4673 command. Example: >
4674 :new | redraw | echo "there is a new window"
4675<
4676 *:echon*
4677:echon {expr1} .. Echoes each {expr1}, without anything added. Also see
4678 |:comment|.
4679 Uses the highlighting set by the |:echohl| command.
4680 Cannot be followed by a comment.
4681 Example: >
4682 :echon "the value of 'shell' is " &shell
4683<
4684 Note the difference between using ":echo", which is a
4685 Vim command, and ":!echo", which is an external shell
4686 command: >
4687 :!echo % --> filename
4688< The arguments of ":!" are expanded, see |:_%|. >
4689 :!echo "%" --> filename or "filename"
4690< Like the previous example. Whether you see the double
4691 quotes or not depends on your 'shell'. >
4692 :echo % --> nothing
4693< The '%' is an illegal character in an expression. >
4694 :echo "%" --> %
4695< This just echoes the '%' character. >
4696 :echo expand("%") --> filename
4697< This calls the expand() function to expand the '%'.
4698
4699 *:echoh* *:echohl*
4700:echoh[l] {name} Use the highlight group {name} for the following
4701 |:echo|, |:echon| and |:echomsg| commands. Also used
4702 for the |input()| prompt. Example: >
4703 :echohl WarningMsg | echo "Don't panic!" | echohl None
4704< Don't forget to set the group back to "None",
4705 otherwise all following echo's will be highlighted.
4706
4707 *:echom* *:echomsg*
4708:echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the
4709 message in the |message-history|.
4710 Spaces are placed between the arguments as with the
4711 |:echo| command. But unprintable characters are
4712 displayed, not interpreted.
4713 Uses the highlighting set by the |:echohl| command.
4714 Example: >
4715 :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."
4716<
4717 *:echoe* *:echoerr*
4718:echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the
4719 message in the |message-history|. When used in a
4720 script or function the line number will be added.
4721 Spaces are placed between the arguments as with the
4722 :echo command. When used inside a try conditional,
4723 the message is raised as an error exception instead
4724 (see |try-echoerr|).
4725 Example: >
4726 :echoerr "This script just failed!"
4727< If you just want a highlighted message use |:echohl|.
4728 And to get a beep: >
4729 :exe "normal \<Esc>"
4730<
4731 *:exe* *:execute*
4732:exe[cute] {expr1} .. Executes the string that results from the evaluation
4733 of {expr1} as an Ex command. Multiple arguments are
4734 concatenated, with a space in between. {expr1} is
4735 used as the processed command, command line editing
4736 keys are not recognized.
4737 Cannot be followed by a comment.
4738 Examples: >
4739 :execute "buffer " nextbuf
4740 :execute "normal " count . "w"
4741<
4742 ":execute" can be used to append a command to commands
4743 that don't accept a '|'. Example: >
4744 :execute '!ls' | echo "theend"
4745
4746< ":execute" is also a nice way to avoid having to type
4747 control characters in a Vim script for a ":normal"
4748 command: >
4749 :execute "normal ixxx\<Esc>"
4750< This has an <Esc> character, see |expr-string|.
4751
4752 Note: The executed string may be any command-line, but
Bram Moolenaard8b02732005-01-14 21:48:43 +00004753 you cannot start or end a "while", "for" or "if"
4754 command. Thus this is illegal: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004755 :execute 'while i > 5'
4756 :execute 'echo "test" | break'
4757<
4758 It is allowed to have a "while" or "if" command
4759 completely in the executed string: >
4760 :execute 'while i < 5 | echo i | let i = i + 1 | endwhile'
4761<
4762
4763 *:comment*
4764 ":execute", ":echo" and ":echon" cannot be followed by
4765 a comment directly, because they see the '"' as the
4766 start of a string. But, you can use '|' followed by a
4767 comment. Example: >
4768 :echo "foo" | "this is a comment
4769
4770==============================================================================
47718. Exception handling *exception-handling*
4772
4773The Vim script language comprises an exception handling feature. This section
4774explains how it can be used in a Vim script.
4775
4776Exceptions may be raised by Vim on an error or on interrupt, see
4777|catch-errors| and |catch-interrupt|. You can also explicitly throw an
4778exception by using the ":throw" command, see |throw-catch|.
4779
4780
4781TRY CONDITIONALS *try-conditionals*
4782
4783Exceptions can be caught or can cause cleanup code to be executed. You can
4784use a try conditional to specify catch clauses (that catch exceptions) and/or
4785a finally clause (to be executed for cleanup).
4786 A try conditional begins with a |:try| command and ends at the matching
4787|:endtry| command. In between, you can use a |:catch| command to start
4788a catch clause, or a |:finally| command to start a finally clause. There may
4789be none or multiple catch clauses, but there is at most one finally clause,
4790which must not be followed by any catch clauses. The lines before the catch
4791clauses and the finally clause is called a try block. >
4792
4793 :try
4794 : ...
4795 : ... TRY BLOCK
4796 : ...
4797 :catch /{pattern}/
4798 : ...
4799 : ... CATCH CLAUSE
4800 : ...
4801 :catch /{pattern}/
4802 : ...
4803 : ... CATCH CLAUSE
4804 : ...
4805 :finally
4806 : ...
4807 : ... FINALLY CLAUSE
4808 : ...
4809 :endtry
4810
4811The try conditional allows to watch code for exceptions and to take the
4812appropriate actions. Exceptions from the try block may be caught. Exceptions
4813from the try block and also the catch clauses may cause cleanup actions.
4814 When no exception is thrown during execution of the try block, the control
4815is transferred to the finally clause, if present. After its execution, the
4816script continues with the line following the ":endtry".
4817 When an exception occurs during execution of the try block, the remaining
4818lines in the try block are skipped. The exception is matched against the
4819patterns specified as arguments to the ":catch" commands. The catch clause
4820after the first matching ":catch" is taken, other catch clauses are not
4821executed. The catch clause ends when the next ":catch", ":finally", or
4822":endtry" command is reached - whatever is first. Then, the finally clause
4823(if present) is executed. When the ":endtry" is reached, the script execution
4824continues in the following line as usual.
4825 When an exception that does not match any of the patterns specified by the
4826":catch" commands is thrown in the try block, the exception is not caught by
4827that try conditional and none of the catch clauses is executed. Only the
4828finally clause, if present, is taken. The exception pends during execution of
4829the finally clause. It is resumed at the ":endtry", so that commands after
4830the ":endtry" are not executed and the exception might be caught elsewhere,
4831see |try-nesting|.
4832 When during execution of a catch clause another exception is thrown, the
4833remaining lines in that catch clause are not executed. The new exception is
4834not matched against the patterns in any of the ":catch" commands of the same
4835try conditional and none of its catch clauses is taken. If there is, however,
4836a finally clause, it is executed, and the exception pends during its
4837execution. The commands following the ":endtry" are not executed. The new
4838exception might, however, be caught elsewhere, see |try-nesting|.
4839 When during execution of the finally clause (if present) an exception is
4840thrown, the remaining lines in the finally clause are skipped. If the finally
4841clause has been taken because of an exception from the try block or one of the
4842catch clauses, the original (pending) exception is discarded. The commands
4843following the ":endtry" are not executed, and the exception from the finally
4844clause is propagated and can be caught elsewhere, see |try-nesting|.
4845
4846The finally clause is also executed, when a ":break" or ":continue" for
4847a ":while" loop enclosing the complete try conditional is executed from the
4848try block or a catch clause. Or when a ":return" or ":finish" is executed
4849from the try block or a catch clause of a try conditional in a function or
4850sourced script, respectively. The ":break", ":continue", ":return", or
4851":finish" pends during execution of the finally clause and is resumed when the
4852":endtry" is reached. It is, however, discarded when an exception is thrown
4853from the finally clause.
4854 When a ":break" or ":continue" for a ":while" loop enclosing the complete
4855try conditional or when a ":return" or ":finish" is encountered in the finally
4856clause, the rest of the finally clause is skipped, and the ":break",
4857":continue", ":return" or ":finish" is executed as usual. If the finally
4858clause has been taken because of an exception or an earlier ":break",
4859":continue", ":return", or ":finish" from the try block or a catch clause,
4860this pending exception or command is discarded.
4861
4862For examples see |throw-catch| and |try-finally|.
4863
4864
4865NESTING OF TRY CONDITIONALS *try-nesting*
4866
4867Try conditionals can be nested arbitrarily. That is, a complete try
4868conditional can be put into the try block, a catch clause, or the finally
4869clause of another try conditional. If the inner try conditional does not
4870catch an exception thrown in its try block or throws a new exception from one
4871of its catch clauses or its finally clause, the outer try conditional is
4872checked according to the rules above. If the inner try conditional is in the
4873try block of the outer try conditional, its catch clauses are checked, but
4874otherwise only the finally clause is executed. It does not matter for
4875nesting, whether the inner try conditional is directly contained in the outer
4876one, or whether the outer one sources a script or calls a function containing
4877the inner try conditional.
4878
4879When none of the active try conditionals catches an exception, just their
4880finally clauses are executed. Thereafter, the script processing terminates.
4881An error message is displayed in case of an uncaught exception explicitly
4882thrown by a ":throw" command. For uncaught error and interrupt exceptions
4883implicitly raised by Vim, the error message(s) or interrupt message are shown
4884as usual.
4885
4886For examples see |throw-catch|.
4887
4888
4889EXAMINING EXCEPTION HANDLING CODE *except-examine*
4890
4891Exception handling code can get tricky. If you are in doubt what happens, set
4892'verbose' to 13 or use the ":13verbose" command modifier when sourcing your
4893script file. Then you see when an exception is thrown, discarded, caught, or
4894finished. When using a verbosity level of at least 14, things pending in
4895a finally clause are also shown. This information is also given in debug mode
4896(see |debug-scripts|).
4897
4898
4899THROWING AND CATCHING EXCEPTIONS *throw-catch*
4900
4901You can throw any number or string as an exception. Use the |:throw| command
4902and pass the value to be thrown as argument: >
4903 :throw 4711
4904 :throw "string"
4905< *throw-expression*
4906You can also specify an expression argument. The expression is then evaluated
4907first, and the result is thrown: >
4908 :throw 4705 + strlen("string")
4909 :throw strpart("strings", 0, 6)
4910
4911An exception might be thrown during evaluation of the argument of the ":throw"
4912command. Unless it is caught there, the expression evaluation is abandoned.
4913The ":throw" command then does not throw a new exception.
4914 Example: >
4915
4916 :function! Foo(arg)
4917 : try
4918 : throw a:arg
4919 : catch /foo/
4920 : endtry
4921 : return 1
4922 :endfunction
4923 :
4924 :function! Bar()
4925 : echo "in Bar"
4926 : return 4710
4927 :endfunction
4928 :
4929 :throw Foo("arrgh") + Bar()
4930
4931This throws "arrgh", and "in Bar" is not displayed since Bar() is not
4932executed. >
4933 :throw Foo("foo") + Bar()
4934however displays "in Bar" and throws 4711.
4935
4936Any other command that takes an expression as argument might also be
4937abandoned by an (uncaught) exception during the expression evaluation. The
4938exception is then propagated to the caller of the command.
4939 Example: >
4940
4941 :if Foo("arrgh")
4942 : echo "then"
4943 :else
4944 : echo "else"
4945 :endif
4946
4947Here neither of "then" or "else" is displayed.
4948
4949 *catch-order*
4950Exceptions can be caught by a try conditional with one or more |:catch|
4951commands, see |try-conditionals|. The values to be caught by each ":catch"
4952command can be specified as a pattern argument. The subsequent catch clause
4953gets executed when a matching exception is caught.
4954 Example: >
4955
4956 :function! Foo(value)
4957 : try
4958 : throw a:value
4959 : catch /^\d\+$/
4960 : echo "Number thrown"
4961 : catch /.*/
4962 : echo "String thrown"
4963 : endtry
4964 :endfunction
4965 :
4966 :call Foo(0x1267)
4967 :call Foo('string')
4968
4969The first call to Foo() displays "Number thrown", the second "String thrown".
4970An exception is matched against the ":catch" commands in the order they are
4971specified. Only the first match counts. So you should place the more
4972specific ":catch" first. The following order does not make sense: >
4973
4974 : catch /.*/
4975 : echo "String thrown"
4976 : catch /^\d\+$/
4977 : echo "Number thrown"
4978
4979The first ":catch" here matches always, so that the second catch clause is
4980never taken.
4981
4982 *throw-variables*
4983If you catch an exception by a general pattern, you may access the exact value
4984in the variable |v:exception|: >
4985
4986 : catch /^\d\+$/
4987 : echo "Number thrown. Value is" v:exception
4988
4989You may also be interested where an exception was thrown. This is stored in
4990|v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the
4991exception most recently caught as long it is not finished.
4992 Example: >
4993
4994 :function! Caught()
4995 : if v:exception != ""
4996 : echo 'Caught "' . v:exception . '" in ' . v:throwpoint
4997 : else
4998 : echo 'Nothing caught'
4999 : endif
5000 :endfunction
5001 :
5002 :function! Foo()
5003 : try
5004 : try
5005 : try
5006 : throw 4711
5007 : finally
5008 : call Caught()
5009 : endtry
5010 : catch /.*/
5011 : call Caught()
5012 : throw "oops"
5013 : endtry
5014 : catch /.*/
5015 : call Caught()
5016 : finally
5017 : call Caught()
5018 : endtry
5019 :endfunction
5020 :
5021 :call Foo()
5022
5023This displays >
5024
5025 Nothing caught
5026 Caught "4711" in function Foo, line 4
5027 Caught "oops" in function Foo, line 10
5028 Nothing caught
5029
5030A practical example: The following command ":LineNumber" displays the line
5031number in the script or function where it has been used: >
5032
5033 :function! LineNumber()
5034 : return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")
5035 :endfunction
5036 :command! LineNumber try | throw "" | catch | echo LineNumber() | endtry
5037<
5038 *try-nested*
5039An exception that is not caught by a try conditional can be caught by
5040a surrounding try conditional: >
5041
5042 :try
5043 : try
5044 : throw "foo"
5045 : catch /foobar/
5046 : echo "foobar"
5047 : finally
5048 : echo "inner finally"
5049 : endtry
5050 :catch /foo/
5051 : echo "foo"
5052 :endtry
5053
5054The inner try conditional does not catch the exception, just its finally
5055clause is executed. The exception is then caught by the outer try
5056conditional. The example displays "inner finally" and then "foo".
5057
5058 *throw-from-catch*
5059You can catch an exception and throw a new one to be caught elsewhere from the
5060catch clause: >
5061
5062 :function! Foo()
5063 : throw "foo"
5064 :endfunction
5065 :
5066 :function! Bar()
5067 : try
5068 : call Foo()
5069 : catch /foo/
5070 : echo "Caught foo, throw bar"
5071 : throw "bar"
5072 : endtry
5073 :endfunction
5074 :
5075 :try
5076 : call Bar()
5077 :catch /.*/
5078 : echo "Caught" v:exception
5079 :endtry
5080
5081This displays "Caught foo, throw bar" and then "Caught bar".
5082
5083 *rethrow*
5084There is no real rethrow in the Vim script language, but you may throw
5085"v:exception" instead: >
5086
5087 :function! Bar()
5088 : try
5089 : call Foo()
5090 : catch /.*/
5091 : echo "Rethrow" v:exception
5092 : throw v:exception
5093 : endtry
5094 :endfunction
5095< *try-echoerr*
5096Note that this method cannot be used to "rethrow" Vim error or interrupt
5097exceptions, because it is not possible to fake Vim internal exceptions.
5098Trying so causes an error exception. You should throw your own exception
5099denoting the situation. If you want to cause a Vim error exception containing
5100the original error exception value, you can use the |:echoerr| command: >
5101
5102 :try
5103 : try
5104 : asdf
5105 : catch /.*/
5106 : echoerr v:exception
5107 : endtry
5108 :catch /.*/
5109 : echo v:exception
5110 :endtry
5111
5112This code displays
5113
5114 Vim(echoerr):Vim:E492: Not an editor command: asdf ~
5115
5116
5117CLEANUP CODE *try-finally*
5118
5119Scripts often change global settings and restore them at their end. If the
5120user however interrupts the script by pressing CTRL-C, the settings remain in
5121an inconsistent state. The same may happen to you in the development phase of
5122a script when an error occurs or you explicitly throw an exception without
5123catching it. You can solve these problems by using a try conditional with
5124a finally clause for restoring the settings. Its execution is guaranteed on
5125normal control flow, on error, on an explicit ":throw", and on interrupt.
5126(Note that errors and interrupts from inside the try conditional are converted
5127to exceptions. When not caught, they terminate the script after the finally
5128clause has been executed.)
5129Example: >
5130
5131 :try
5132 : let s:saved_ts = &ts
5133 : set ts=17
5134 :
5135 : " Do the hard work here.
5136 :
5137 :finally
5138 : let &ts = s:saved_ts
5139 : unlet s:saved_ts
5140 :endtry
5141
5142This method should be used locally whenever a function or part of a script
5143changes global settings which need to be restored on failure or normal exit of
5144that function or script part.
5145
5146 *break-finally*
5147Cleanup code works also when the try block or a catch clause is left by
5148a ":continue", ":break", ":return", or ":finish".
5149 Example: >
5150
5151 :let first = 1
5152 :while 1
5153 : try
5154 : if first
5155 : echo "first"
5156 : let first = 0
5157 : continue
5158 : else
5159 : throw "second"
5160 : endif
5161 : catch /.*/
5162 : echo v:exception
5163 : break
5164 : finally
5165 : echo "cleanup"
5166 : endtry
5167 : echo "still in while"
5168 :endwhile
5169 :echo "end"
5170
5171This displays "first", "cleanup", "second", "cleanup", and "end". >
5172
5173 :function! Foo()
5174 : try
5175 : return 4711
5176 : finally
5177 : echo "cleanup\n"
5178 : endtry
5179 : echo "Foo still active"
5180 :endfunction
5181 :
5182 :echo Foo() "returned by Foo"
5183
5184This displays "cleanup" and "4711 returned by Foo". You don't need to add an
5185extra ":return" in the finally clause. (Above all, this would override the
5186return value.)
5187
5188 *except-from-finally*
5189Using either of ":continue", ":break", ":return", ":finish", or ":throw" in
5190a finally clause is possible, but not recommended since it abandons the
5191cleanup actions for the try conditional. But, of course, interrupt and error
5192exceptions might get raised from a finally clause.
5193 Example where an error in the finally clause stops an interrupt from
5194working correctly: >
5195
5196 :try
5197 : try
5198 : echo "Press CTRL-C for interrupt"
5199 : while 1
5200 : endwhile
5201 : finally
5202 : unlet novar
5203 : endtry
5204 :catch /novar/
5205 :endtry
5206 :echo "Script still running"
5207 :sleep 1
5208
5209If you need to put commands that could fail into a finally clause, you should
5210think about catching or ignoring the errors in these commands, see
5211|catch-errors| and |ignore-errors|.
5212
5213
5214CATCHING ERRORS *catch-errors*
5215
5216If you want to catch specific errors, you just have to put the code to be
5217watched in a try block and add a catch clause for the error message. The
5218presence of the try conditional causes all errors to be converted to an
5219exception. No message is displayed and |v:errmsg| is not set then. To find
5220the right pattern for the ":catch" command, you have to know how the format of
5221the error exception is.
5222 Error exceptions have the following format: >
5223
5224 Vim({cmdname}):{errmsg}
5225or >
5226 Vim:{errmsg}
5227
5228{cmdname} is the name of the command that failed; the second form is used when
5229the command name is not known. {errmsg} is the error message usually produced
5230when the error occurs outside try conditionals. It always begins with
5231a capital "E", followed by a two or three-digit error number, a colon, and
5232a space.
5233
5234Examples:
5235
5236The command >
5237 :unlet novar
5238normally produces the error message >
5239 E108: No such variable: "novar"
5240which is converted inside try conditionals to an exception >
5241 Vim(unlet):E108: No such variable: "novar"
5242
5243The command >
5244 :dwim
5245normally produces the error message >
5246 E492: Not an editor command: dwim
5247which is converted inside try conditionals to an exception >
5248 Vim:E492: Not an editor command: dwim
5249
5250You can catch all ":unlet" errors by a >
5251 :catch /^Vim(unlet):/
5252or all errors for misspelled command names by a >
5253 :catch /^Vim:E492:/
5254
5255Some error messages may be produced by different commands: >
5256 :function nofunc
5257and >
5258 :delfunction nofunc
5259both produce the error message >
5260 E128: Function name must start with a capital: nofunc
5261which is converted inside try conditionals to an exception >
5262 Vim(function):E128: Function name must start with a capital: nofunc
5263or >
5264 Vim(delfunction):E128: Function name must start with a capital: nofunc
5265respectively. You can catch the error by its number independently on the
5266command that caused it if you use the following pattern: >
5267 :catch /^Vim(\a\+):E128:/
5268
5269Some commands like >
5270 :let x = novar
5271produce multiple error messages, here: >
5272 E121: Undefined variable: novar
5273 E15: Invalid expression: novar
5274Only the first is used for the exception value, since it is the most specific
5275one (see |except-several-errors|). So you can catch it by >
5276 :catch /^Vim(\a\+):E121:/
5277
5278You can catch all errors related to the name "nofunc" by >
5279 :catch /\<nofunc\>/
5280
5281You can catch all Vim errors in the ":write" and ":read" commands by >
5282 :catch /^Vim(\(write\|read\)):E\d\+:/
5283
5284You can catch all Vim errors by the pattern >
5285 :catch /^Vim\((\a\+)\)\=:E\d\+:/
5286<
5287 *catch-text*
5288NOTE: You should never catch the error message text itself: >
5289 :catch /No such variable/
5290only works in the english locale, but not when the user has selected
5291a different language by the |:language| command. It is however helpful to
5292cite the message text in a comment: >
5293 :catch /^Vim(\a\+):E108:/ " No such variable
5294
5295
5296IGNORING ERRORS *ignore-errors*
5297
5298You can ignore errors in a specific Vim command by catching them locally: >
5299
5300 :try
5301 : write
5302 :catch
5303 :endtry
5304
5305But you are strongly recommended NOT to use this simple form, since it could
5306catch more than you want. With the ":write" command, some autocommands could
5307be executed and cause errors not related to writing, for instance: >
5308
5309 :au BufWritePre * unlet novar
5310
5311There could even be such errors you are not responsible for as a script
5312writer: a user of your script might have defined such autocommands. You would
5313then hide the error from the user.
5314 It is much better to use >
5315
5316 :try
5317 : write
5318 :catch /^Vim(write):/
5319 :endtry
5320
5321which only catches real write errors. So catch only what you'd like to ignore
5322intentionally.
5323
5324For a single command that does not cause execution of autocommands, you could
5325even suppress the conversion of errors to exceptions by the ":silent!"
5326command: >
5327 :silent! nunmap k
5328This works also when a try conditional is active.
5329
5330
5331CATCHING INTERRUPTS *catch-interrupt*
5332
5333When there are active try conditionals, an interrupt (CTRL-C) is converted to
5334the exception "Vim:Interrupt". You can catch it like every exception. The
5335script is not terminated, then.
5336 Example: >
5337
5338 :function! TASK1()
5339 : sleep 10
5340 :endfunction
5341
5342 :function! TASK2()
5343 : sleep 20
5344 :endfunction
5345
5346 :while 1
5347 : let command = input("Type a command: ")
5348 : try
5349 : if command == ""
5350 : continue
5351 : elseif command == "END"
5352 : break
5353 : elseif command == "TASK1"
5354 : call TASK1()
5355 : elseif command == "TASK2"
5356 : call TASK2()
5357 : else
5358 : echo "\nIllegal command:" command
5359 : continue
5360 : endif
5361 : catch /^Vim:Interrupt$/
5362 : echo "\nCommand interrupted"
5363 : " Caught the interrupt. Continue with next prompt.
5364 : endtry
5365 :endwhile
5366
5367You can interrupt a task here by pressing CTRL-C; the script then asks for
5368a new command. If you press CTRL-C at the prompt, the script is terminated.
5369
5370For testing what happens when CTRL-C would be pressed on a specific line in
5371your script, use the debug mode and execute the |>quit| or |>interrupt|
5372command on that line. See |debug-scripts|.
5373
5374
5375CATCHING ALL *catch-all*
5376
5377The commands >
5378
5379 :catch /.*/
5380 :catch //
5381 :catch
5382
5383catch everything, error exceptions, interrupt exceptions and exceptions
5384explicitly thrown by the |:throw| command. This is useful at the top level of
5385a script in order to catch unexpected things.
5386 Example: >
5387
5388 :try
5389 :
5390 : " do the hard work here
5391 :
5392 :catch /MyException/
5393 :
5394 : " handle known problem
5395 :
5396 :catch /^Vim:Interrupt$/
5397 : echo "Script interrupted"
5398 :catch /.*/
5399 : echo "Internal error (" . v:exception . ")"
5400 : echo " - occurred at " . v:throwpoint
5401 :endtry
5402 :" end of script
5403
5404Note: Catching all might catch more things than you want. Thus, you are
5405strongly encouraged to catch only for problems that you can really handle by
5406specifying a pattern argument to the ":catch".
5407 Example: Catching all could make it nearly impossible to interrupt a script
5408by pressing CTRL-C: >
5409
5410 :while 1
5411 : try
5412 : sleep 1
5413 : catch
5414 : endtry
5415 :endwhile
5416
5417
5418EXCEPTIONS AND AUTOCOMMANDS *except-autocmd*
5419
5420Exceptions may be used during execution of autocommands. Example: >
5421
5422 :autocmd User x try
5423 :autocmd User x throw "Oops!"
5424 :autocmd User x catch
5425 :autocmd User x echo v:exception
5426 :autocmd User x endtry
5427 :autocmd User x throw "Arrgh!"
5428 :autocmd User x echo "Should not be displayed"
5429 :
5430 :try
5431 : doautocmd User x
5432 :catch
5433 : echo v:exception
5434 :endtry
5435
5436This displays "Oops!" and "Arrgh!".
5437
5438 *except-autocmd-Pre*
5439For some commands, autocommands get executed before the main action of the
5440command takes place. If an exception is thrown and not caught in the sequence
5441of autocommands, the sequence and the command that caused its execution are
5442abandoned and the exception is propagated to the caller of the command.
5443 Example: >
5444
5445 :autocmd BufWritePre * throw "FAIL"
5446 :autocmd BufWritePre * echo "Should not be displayed"
5447 :
5448 :try
5449 : write
5450 :catch
5451 : echo "Caught:" v:exception "from" v:throwpoint
5452 :endtry
5453
5454Here, the ":write" command does not write the file currently being edited (as
5455you can see by checking 'modified'), since the exception from the BufWritePre
5456autocommand abandons the ":write". The exception is then caught and the
5457script displays: >
5458
5459 Caught: FAIL from BufWrite Auto commands for "*"
5460<
5461 *except-autocmd-Post*
5462For some commands, autocommands get executed after the main action of the
5463command has taken place. If this main action fails and the command is inside
5464an active try conditional, the autocommands are skipped and an error exception
5465is thrown that can be caught by the caller of the command.
5466 Example: >
5467
5468 :autocmd BufWritePost * echo "File successfully written!"
5469 :
5470 :try
5471 : write /i/m/p/o/s/s/i/b/l/e
5472 :catch
5473 : echo v:exception
5474 :endtry
5475
5476This just displays: >
5477
5478 Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)
5479
5480If you really need to execute the autocommands even when the main action
5481fails, trigger the event from the catch clause.
5482 Example: >
5483
5484 :autocmd BufWritePre * set noreadonly
5485 :autocmd BufWritePost * set readonly
5486 :
5487 :try
5488 : write /i/m/p/o/s/s/i/b/l/e
5489 :catch
5490 : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e
5491 :endtry
5492<
5493You can also use ":silent!": >
5494
5495 :let x = "ok"
5496 :let v:errmsg = ""
5497 :autocmd BufWritePost * if v:errmsg != ""
5498 :autocmd BufWritePost * let x = "after fail"
5499 :autocmd BufWritePost * endif
5500 :try
5501 : silent! write /i/m/p/o/s/s/i/b/l/e
5502 :catch
5503 :endtry
5504 :echo x
5505
5506This displays "after fail".
5507
5508If the main action of the command does not fail, exceptions from the
5509autocommands will be catchable by the caller of the command: >
5510
5511 :autocmd BufWritePost * throw ":-("
5512 :autocmd BufWritePost * echo "Should not be displayed"
5513 :
5514 :try
5515 : write
5516 :catch
5517 : echo v:exception
5518 :endtry
5519<
5520 *except-autocmd-Cmd*
5521For some commands, the normal action can be replaced by a sequence of
5522autocommands. Exceptions from that sequence will be catchable by the caller
5523of the command.
5524 Example: For the ":write" command, the caller cannot know whether the file
5525had actually been written when the exception occurred. You need to tell it in
5526some way. >
5527
5528 :if !exists("cnt")
5529 : let cnt = 0
5530 :
5531 : autocmd BufWriteCmd * if &modified
5532 : autocmd BufWriteCmd * let cnt = cnt + 1
5533 : autocmd BufWriteCmd * if cnt % 3 == 2
5534 : autocmd BufWriteCmd * throw "BufWriteCmdError"
5535 : autocmd BufWriteCmd * endif
5536 : autocmd BufWriteCmd * write | set nomodified
5537 : autocmd BufWriteCmd * if cnt % 3 == 0
5538 : autocmd BufWriteCmd * throw "BufWriteCmdError"
5539 : autocmd BufWriteCmd * endif
5540 : autocmd BufWriteCmd * echo "File successfully written!"
5541 : autocmd BufWriteCmd * endif
5542 :endif
5543 :
5544 :try
5545 : write
5546 :catch /^BufWriteCmdError$/
5547 : if &modified
5548 : echo "Error on writing (file contents not changed)"
5549 : else
5550 : echo "Error after writing"
5551 : endif
5552 :catch /^Vim(write):/
5553 : echo "Error on writing"
5554 :endtry
5555
5556When this script is sourced several times after making changes, it displays
5557first >
5558 File successfully written!
5559then >
5560 Error on writing (file contents not changed)
5561then >
5562 Error after writing
5563etc.
5564
5565 *except-autocmd-ill*
5566You cannot spread a try conditional over autocommands for different events.
5567The following code is ill-formed: >
5568
5569 :autocmd BufWritePre * try
5570 :
5571 :autocmd BufWritePost * catch
5572 :autocmd BufWritePost * echo v:exception
5573 :autocmd BufWritePost * endtry
5574 :
5575 :write
5576
5577
5578EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS *except-hier-param*
5579
5580Some programming languages allow to use hierarchies of exception classes or to
5581pass additional information with the object of an exception class. You can do
5582similar things in Vim.
5583 In order to throw an exception from a hierarchy, just throw the complete
5584class name with the components separated by a colon, for instance throw the
5585string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library.
5586 When you want to pass additional information with your exception class, add
5587it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)"
5588for an error when writing "myfile".
5589 With the appropriate patterns in the ":catch" command, you can catch for
5590base classes or derived classes of your hierarchy. Additional information in
5591parentheses can be cut out from |v:exception| with the ":substitute" command.
5592 Example: >
5593
5594 :function! CheckRange(a, func)
5595 : if a:a < 0
5596 : throw "EXCEPT:MATHERR:RANGE(" . a:func . ")"
5597 : endif
5598 :endfunction
5599 :
5600 :function! Add(a, b)
5601 : call CheckRange(a:a, "Add")
5602 : call CheckRange(a:b, "Add")
5603 : let c = a:a + a:b
5604 : if c < 0
5605 : throw "EXCEPT:MATHERR:OVERFLOW"
5606 : endif
5607 : return c
5608 :endfunction
5609 :
5610 :function! Div(a, b)
5611 : call CheckRange(a:a, "Div")
5612 : call CheckRange(a:b, "Div")
5613 : if (a:b == 0)
5614 : throw "EXCEPT:MATHERR:ZERODIV"
5615 : endif
5616 : return a:a / a:b
5617 :endfunction
5618 :
5619 :function! Write(file)
5620 : try
5621 : execute "write" a:file
5622 : catch /^Vim(write):/
5623 : throw "EXCEPT:IO(" . getcwd() . ", " . a:file . "):WRITEERR"
5624 : endtry
5625 :endfunction
5626 :
5627 :try
5628 :
5629 : " something with arithmetics and I/O
5630 :
5631 :catch /^EXCEPT:MATHERR:RANGE/
5632 : let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "")
5633 : echo "Range error in" function
5634 :
5635 :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV
5636 : echo "Math error"
5637 :
5638 :catch /^EXCEPT:IO/
5639 : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "")
5640 : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "")
5641 : if file !~ '^/'
5642 : let file = dir . "/" . file
5643 : endif
5644 : echo 'I/O error for "' . file . '"'
5645 :
5646 :catch /^EXCEPT/
5647 : echo "Unspecified error"
5648 :
5649 :endtry
5650
5651The exceptions raised by Vim itself (on error or when pressing CTRL-C) use
5652a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself
5653exceptions with the "Vim" prefix; they are reserved for Vim.
5654 Vim error exceptions are parameterized with the name of the command that
5655failed, if known. See |catch-errors|.
5656
5657
5658PECULIARITIES
5659 *except-compat*
5660The exception handling concept requires that the command sequence causing the
5661exception is aborted immediately and control is transferred to finally clauses
5662and/or a catch clause.
5663
5664In the Vim script language there are cases where scripts and functions
5665continue after an error: in functions without the "abort" flag or in a command
5666after ":silent!", control flow goes to the following line, and outside
5667functions, control flow goes to the line following the outermost ":endwhile"
5668or ":endif". On the other hand, errors should be catchable as exceptions
5669(thus, requiring the immediate abortion).
5670
5671This problem has been solved by converting errors to exceptions and using
5672immediate abortion (if not suppressed by ":silent!") only when a try
5673conditional is active. This is no restriction since an (error) exception can
5674be caught only from an active try conditional. If you want an immediate
5675termination without catching the error, just use a try conditional without
5676catch clause. (You can cause cleanup code being executed before termination
5677by specifying a finally clause.)
5678
5679When no try conditional is active, the usual abortion and continuation
5680behavior is used instead of immediate abortion. This ensures compatibility of
5681scripts written for Vim 6.1 and earlier.
5682
5683However, when sourcing an existing script that does not use exception handling
5684commands (or when calling one of its functions) from inside an active try
5685conditional of a new script, you might change the control flow of the existing
5686script on error. You get the immediate abortion on error and can catch the
5687error in the new script. If however the sourced script suppresses error
5688messages by using the ":silent!" command (checking for errors by testing
5689|v:errmsg| if appropriate), its execution path is not changed. The error is
5690not converted to an exception. (See |:silent|.) So the only remaining cause
5691where this happens is for scripts that don't care about errors and produce
5692error messages. You probably won't want to use such code from your new
5693scripts.
5694
5695 *except-syntax-err*
5696Syntax errors in the exception handling commands are never caught by any of
5697the ":catch" commands of the try conditional they belong to. Its finally
5698clauses, however, is executed.
5699 Example: >
5700
5701 :try
5702 : try
5703 : throw 4711
5704 : catch /\(/
5705 : echo "in catch with syntax error"
5706 : catch
5707 : echo "inner catch-all"
5708 : finally
5709 : echo "inner finally"
5710 : endtry
5711 :catch
5712 : echo 'outer catch-all caught "' . v:exception . '"'
5713 : finally
5714 : echo "outer finally"
5715 :endtry
5716
5717This displays: >
5718 inner finally
5719 outer catch-all caught "Vim(catch):E54: Unmatched \("
5720 outer finally
5721The original exception is discarded and an error exception is raised, instead.
5722
5723 *except-single-line*
5724The ":try", ":catch", ":finally", and ":endtry" commands can be put on
5725a single line, but then syntax errors may make it difficult to recognize the
5726"catch" line, thus you better avoid this.
5727 Example: >
5728 :try | unlet! foo # | catch | endtry
5729raises an error exception for the trailing characters after the ":unlet!"
5730argument, but does not see the ":catch" and ":endtry" commands, so that the
5731error exception is discarded and the "E488: Trailing characters" message gets
5732displayed.
5733
5734 *except-several-errors*
5735When several errors appear in a single command, the first error message is
5736usually the most specific one and therefor converted to the error exception.
5737 Example: >
5738 echo novar
5739causes >
5740 E121: Undefined variable: novar
5741 E15: Invalid expression: novar
5742The value of the error exception inside try conditionals is: >
5743 Vim(echo):E121: Undefined variable: novar
5744< *except-syntax-error*
5745But when a syntax error is detected after a normal error in the same command,
5746the syntax error is used for the exception being thrown.
5747 Example: >
5748 unlet novar #
5749causes >
5750 E108: No such variable: "novar"
5751 E488: Trailing characters
5752The value of the error exception inside try conditionals is: >
5753 Vim(unlet):E488: Trailing characters
5754This is done because the syntax error might change the execution path in a way
5755not intended by the user. Example: >
5756 try
5757 try | unlet novar # | catch | echo v:exception | endtry
5758 catch /.*/
5759 echo "outer catch:" v:exception
5760 endtry
5761This displays "outer catch: Vim(unlet):E488: Trailing characters", and then
5762a "E600: Missing :endtry" error message is given, see |except-single-line|.
5763
5764==============================================================================
57659. Examples *eval-examples*
5766
5767Printing in Hex ~
5768>
5769 :" The function Nr2Hex() returns the Hex string of a number.
5770 :func Nr2Hex(nr)
5771 : let n = a:nr
5772 : let r = ""
5773 : while n
5774 : let r = '0123456789ABCDEF'[n % 16] . r
5775 : let n = n / 16
5776 : endwhile
5777 : return r
5778 :endfunc
5779
5780 :" The function String2Hex() converts each character in a string to a two
5781 :" character Hex string.
5782 :func String2Hex(str)
5783 : let out = ''
5784 : let ix = 0
5785 : while ix < strlen(a:str)
5786 : let out = out . Nr2Hex(char2nr(a:str[ix]))
5787 : let ix = ix + 1
5788 : endwhile
5789 : return out
5790 :endfunc
5791
5792Example of its use: >
5793 :echo Nr2Hex(32)
5794result: "20" >
5795 :echo String2Hex("32")
5796result: "3332"
5797
5798
5799Sorting lines (by Robert Webb) ~
5800
5801Here is a Vim script to sort lines. Highlight the lines in Vim and type
5802":Sort". This doesn't call any external programs so it'll work on any
5803platform. The function Sort() actually takes the name of a comparison
5804function as its argument, like qsort() does in C. So you could supply it
5805with different comparison functions in order to sort according to date etc.
5806>
5807 :" Function for use with Sort(), to compare two strings.
5808 :func! Strcmp(str1, str2)
5809 : if (a:str1 < a:str2)
5810 : return -1
5811 : elseif (a:str1 > a:str2)
5812 : return 1
5813 : else
5814 : return 0
5815 : endif
5816 :endfunction
5817
5818 :" Sort lines. SortR() is called recursively.
5819 :func! SortR(start, end, cmp)
5820 : if (a:start >= a:end)
5821 : return
5822 : endif
5823 : let partition = a:start - 1
5824 : let middle = partition
5825 : let partStr = getline((a:start + a:end) / 2)
5826 : let i = a:start
5827 : while (i <= a:end)
5828 : let str = getline(i)
5829 : exec "let result = " . a:cmp . "(str, partStr)"
5830 : if (result <= 0)
5831 : " Need to put it before the partition. Swap lines i and partition.
5832 : let partition = partition + 1
5833 : if (result == 0)
5834 : let middle = partition
5835 : endif
5836 : if (i != partition)
5837 : let str2 = getline(partition)
5838 : call setline(i, str2)
5839 : call setline(partition, str)
5840 : endif
5841 : endif
5842 : let i = i + 1
5843 : endwhile
5844
5845 : " Now we have a pointer to the "middle" element, as far as partitioning
5846 : " goes, which could be anywhere before the partition. Make sure it is at
5847 : " the end of the partition.
5848 : if (middle != partition)
5849 : let str = getline(middle)
5850 : let str2 = getline(partition)
5851 : call setline(middle, str2)
5852 : call setline(partition, str)
5853 : endif
5854 : call SortR(a:start, partition - 1, a:cmp)
5855 : call SortR(partition + 1, a:end, a:cmp)
5856 :endfunc
5857
5858 :" To Sort a range of lines, pass the range to Sort() along with the name of a
5859 :" function that will compare two lines.
5860 :func! Sort(cmp) range
5861 : call SortR(a:firstline, a:lastline, a:cmp)
5862 :endfunc
5863
5864 :" :Sort takes a range of lines and sorts them.
5865 :command! -nargs=0 -range Sort <line1>,<line2>call Sort("Strcmp")
5866<
5867 *sscanf*
5868There is no sscanf() function in Vim. If you need to extract parts from a
5869line, you can use matchstr() and substitute() to do it. This example shows
5870how to get the file name, line number and column number out of a line like
5871"foobar.txt, 123, 45". >
5872 :" Set up the match bit
5873 :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)'
5874 :"get the part matching the whole expression
5875 :let l = matchstr(line, mx)
5876 :"get each item out of the match
5877 :let file = substitute(l, mx, '\1', '')
5878 :let lnum = substitute(l, mx, '\2', '')
5879 :let col = substitute(l, mx, '\3', '')
5880
5881The input is in the variable "line", the results in the variables "file",
5882"lnum" and "col". (idea from Michael Geddes)
5883
5884==============================================================================
588510. No +eval feature *no-eval-feature*
5886
5887When the |+eval| feature was disabled at compile time, none of the expression
5888evaluation commands are available. To prevent this from causing Vim scripts
5889to generate all kinds of errors, the ":if" and ":endif" commands are still
5890recognized, though the argument of the ":if" and everything between the ":if"
5891and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but
5892only if the commands are at the start of the line. The ":else" command is not
5893recognized.
5894
5895Example of how to avoid executing commands when the |+eval| feature is
5896missing: >
5897
5898 :if 1
5899 : echo "Expression evaluation is compiled in"
5900 :else
5901 : echo "You will _never_ see this message"
5902 :endif
5903
5904==============================================================================
590511. The sandbox *eval-sandbox* *sandbox* *E48*
5906
5907The 'foldexpr', 'includeexpr', 'indentexpr', 'statusline' and 'foldtext'
5908options are evaluated in a sandbox. This means that you are protected from
5909these expressions having nasty side effects. This gives some safety for when
5910these options are set from a modeline. It is also used when the command from
5911a tags file is executed.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00005912The sandbox is also used for the |:sandbox| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005913
5914These items are not allowed in the sandbox:
5915 - changing the buffer text
5916 - defining or changing mapping, autocommands, functions, user commands
5917 - setting certain options (see |option-summary|)
5918 - executing a shell command
5919 - reading or writing a file
5920 - jumping to another buffer or editing a file
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00005921This is not guaranteed 100% secure, but it should block most attacks.
5922
5923 *:san* *:sandbox*
5924:sandbox {cmd} Execute {cmd} in the sandbox. Useful to evaluate an
5925 option that may have been set from a modeline, e.g.
5926 'foldexpr'.
5927
Bram Moolenaar071d4272004-06-13 20:20:40 +00005928
5929 vim:tw=78:ts=8:ft=help:norl: