Mercurial > vim

comparison runtime/doc/eval.txt @ 114:f6e567606d47

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
updated for version 7.0041
author vimboss
date Mon, 17 Jan 2005 22:16:15 +0000
parents 375b1d0f97b0
children e8f07016e34d
comparison
equal deleted inserted replaced
113:3ab5fe5c1bb0 114:f6e567606d47
1 *eval.txt* For Vim version 7.0aa. Last change: 2005 Jan 16 1 *eval.txt* For Vim version 7.0aa. Last change: 2005 Jan 17
2 2
3 3
4 VIM REFERENCE MANUAL by Bram Moolenaar 4 VIM REFERENCE MANUAL by Bram Moolenaar
5 5
6 6
33 33
34 ============================================================================== 34 ==============================================================================
35 1. Variables *variables* 35 1. Variables *variables*
36 36
37 1.1 Variable types ~ 37 1.1 Variable types ~
38 38 *E712*
39 There are four types of variables: 39 There are four types of variables:
40 40
41 Number A 32 bit signed number. 41 Number A 32 bit signed number.
42 Examples: -123 0x10 0177 42 Examples: -123 0x10 0177
43 43
78 Note that in the command > 78 Note that in the command >
79 :if "foo" 79 :if "foo"
80 "foo" is converted to 0, which means FALSE. To test for a non-empty string, 80 "foo" is converted to 0, which means FALSE. To test for a non-empty string,
81 use strlen(): > 81 use strlen(): >
82 :if strlen("foo") 82 :if strlen("foo")
83 83 < *E728* *E729* *E730* *E731*
84 List and Funcref types are not automatically converted. 84 List and Funcref types are not automatically converted.
85 85
86 *E706* 86 *E706*
87 You will get an error if you try to change the type of a variable. You need 87 You will get an error if you try to change the type of a variable. You need
88 to |:unlet| it first to avoid this error. String and Number are considered 88 to |:unlet| it first to avoid this error. String and Number are considered
91 :let l = 44 " changes type from String to Number 91 :let l = 44 " changes type from String to Number
92 :let l = [1, 2, 3] " error! 92 :let l = [1, 2, 3] " error!
93 93
94 94
95 1.2 Function references ~ 95 1.2 Function references ~
96 *Funcref* *E695* *E703* 96 *Funcref* *E695* *E703* *E718*
97 A Funcref variable is obtained with the |function()| function. It can be used 97 A Funcref variable is obtained with the |function()| function. It can be used
98 in an expression to invoke the function it refers to by using it in the place 98 in an expression in the place of a function name, before the parenthesis
99 of a function name, before the parenthesis around the arguments. Example: > 99 around the arguments, to invoke the function it refers to. Example: >
100 100
101 :let Fn = function("MyFunc") 101 :let Fn = function("MyFunc")
102 :echo Fn() 102 :echo Fn()
103 < 103 < *E704* *E705* *E707*
104 *E704* *E705* *E707*
105 A Funcref variable must start with a capital, "s:", "w:" or "b:". You cannot 104 A Funcref variable must start with a capital, "s:", "w:" or "b:". You cannot
106 have both a Funcref variable and a function with the same name. 105 have both a Funcref variable and a function with the same name.
107 106
108 Note that a Funcref cannot be used with the |:call| command, because its 107 A special case is defining a function and directly assigning its Funcref to a
109 argument is not an expression. 108 Dictionary entry. Example: >
109 :function dict.init() dict
110 : let self.val = 0
111 :endfunction
112
113 The key of the Dictionary can start with a lower case letter. The actual
114 function name is not used here. Also see |numbered-function|.
115
116 A Funcref can also be used with the |:call| command: >
117 :call Fn()
118 :call dict.init()
110 119
111 The name of the referenced function can be obtained with |string()|. > 120 The name of the referenced function can be obtained with |string()|. >
112 :echo "The function is " . string(Myfunc) 121 :let func = string(Myfunc)
113 122
114 You can use |call()| to invoke a Funcref and use a list variable for the 123 You can use |call()| to invoke a Funcref and use a list variable for the
115 arguments: > 124 arguments: >
116 :let r = call(Myfunc, mylist) 125 :let r = call(Myfunc, mylist)
117 126
118 127
119 1.3 Lists ~ 128 1.3 Lists ~
120 *List* *E686* *E712* 129 *List* *E686*
121 A List is an ordered sequence of items. An item can be of any type. Items 130 A List is an ordered sequence of items. An item can be of any type. Items
122 can be accessed by their index number. Items can be added and removed at any 131 can be accessed by their index number. Items can be added and removed at any
123 position in the sequence. 132 position in the sequence.
124 133
125 134
192 change "bb": > 201 change "bb": >
193 :let aa = [1, 2, 3] 202 :let aa = [1, 2, 3]
194 :let bb = aa 203 :let bb = aa
195 :call add(aa, 4) 204 :call add(aa, 4)
196 :echo bb 205 :echo bb
197 [1, 2, 3, 4] 206 < [1, 2, 3, 4]
198 207
199 Making a copy of a list is done with the |copy()| function. Using [:] also 208 Making a copy of a list is done with the |copy()| function. Using [:] also
200 works, as explained above. This creates a shallow copy of the list: Changing 209 works, as explained above. This creates a shallow copy of the list: Changing
201 a list item in the list will also change the item in the copied list: > 210 a list item in the list will also change the item in the copied list: >
202 :let aa = [[1, 'a'], 2, 3] 211 :let aa = [[1, 'a'], 2, 3]
203 :let bb = copy(aa) 212 :let bb = copy(aa)
204 :let aa = aa + [4] 213 :call add(aa, 4)
205 :let aa[0][1] = 'aaa' 214 :let aa[0][1] = 'aaa'
206 :echo aa 215 :echo aa
207 [[1, aaa], 2, 3, 4] 216 < [[1, aaa], 2, 3, 4] >
208 :echo bb 217 :echo bb
209 [[1, aaa], 2, 3] 218 < [[1, aaa], 2, 3]
210 219
211 To make a completely independent list use |deepcopy()|. This also makes a 220 To make a completely independent list use |deepcopy()|. This also makes a
212 copy of the values in the list, recursively. 221 copy of the values in the list, recursively. Up to a hundred levels deep.
213 222
214 The operator "is" can be used to check if two variables refer to the same 223 The operator "is" can be used to check if two variables refer to the same
215 list. "isnot" does the opposite. In contrast "==" compares if two lists have 224 List. "isnot" does the opposite. In contrast "==" compares if two lists have
216 the same value. > 225 the same value. >
217 :let alist = [1, 2, 3] 226 :let alist = [1, 2, 3]
218 :let blist = [1, 2, 3] 227 :let blist = [1, 2, 3]
219 :echo alist is blist 228 :echo alist is blist
220 0 229 < 0 >
221 :echo alist == blist 230 :echo alist == blist
222 1 231 < 1
223 232
224 233
225 List unpack ~ 234 List unpack ~
226 235
227 To unpack the items in a list to individual variables, put the variables in 236 To unpack the items in a list to individual variables, put the variables in
247 To change a specific item of a list use |:let| this way: > 256 To change a specific item of a list use |:let| this way: >
248 :let list[4] = "four" 257 :let list[4] = "four"
249 :let listlist[0][3] = item 258 :let listlist[0][3] = item
250 259
251 To change part of a list you can specify the first and last item to be 260 To change part of a list you can specify the first and last item to be
252 modified. The value must match the range of replaced items: > 261 modified. The value must at least have the number of items in the range: >
253 :let list[3:5] = [3, 4, 5] 262 :let list[3:5] = [3, 4, 5]
254 263
255 Adding and removing items from a list is done with functions. Here are a few 264 Adding and removing items from a list is done with functions. Here are a few
256 examples: > 265 examples: >
257 :call insert(list, 'a') " prepend item 'a' 266 :call insert(list, 'a') " prepend item 'a'
258 :call insert(list, 'a', 3) " insert item 'a' before list[3] 267 :call insert(list, 'a', 3) " insert item 'a' before list[3]
259 :call add(list, "new") " append String item 268 :call add(list, "new") " append String item
260 :call add(list, [1, 2]) " append List as one new item 269 :call add(list, [1, 2]) " append a List as one new item
261 :call extend(list, [1, 2]) " extend the list with two more items 270 :call extend(list, [1, 2]) " extend the list with two more items
262 :let i = remove(list, 3) " remove item 3 271 :let i = remove(list, 3) " remove item 3
263 :unlet list[3] " idem 272 :unlet list[3] " idem
264 :let l = remove(list, 3, -1) " remove items 3 to last item 273 :let l = remove(list, 3, -1) " remove items 3 to last item
265 :unlet list[3 : ] " idem 274 :unlet list[3 : ] " idem
266 :call filter(list, 'v:val =~ "x"') " remove items with an 'x' 275 :call filter(list, 'v:val !~ "x"') " remove items with an 'x'
267 276
268 Changing the oder of items in a list: > 277 Changing the order of items in a list: >
269 :call sort(list) " sort a list alphabetically 278 :call sort(list) " sort a list alphabetically
270 :call reverse(list) " reverse the order of items 279 :call reverse(list) " reverse the order of items
271 280
272 281
273 For loop ~ 282 For loop ~
274 283
275 The |:for| loop executes commands for each item in a list. A variable is set 284 The |:for| loop executes commands for each item in a list. A variable is set
276 to each item in the list in sequence. Example: > 285 to each item in the list in sequence. Example: >
277 :for i in mylist 286 :for item in mylist
278 : call Doit(i) 287 : call Doit(item)
279 :endfor 288 :endfor
280 289
281 This works like: > 290 This works like: >
282 :let index = 0 291 :let index = 0
283 :while index < len(mylist) 292 :while index < len(mylist)
284 : let i = mylist[index] 293 : let item = mylist[index]
285 : :call Doit(i) 294 : :call Doit(item)
286 : let index = index + 1 295 : let index = index + 1
287 :endwhile 296 :endwhile
288 297
289 Note that all items in the list should be of the same type, otherwise this 298 Note that all items in the list should be of the same type, otherwise this
290 results in an error |E706|. To avoid this |:unlet| the variable at the end of 299 results in error |E706|. To avoid this |:unlet| the variable at the end of
291 the loop. 300 the loop.
292 301
293 If all you want to do is modify each item in the list then the |map()| 302 If all you want to do is modify each item in the list then the |map()|
294 function might be a simpler method than a for loop. 303 function will be a simpler method than a for loop.
295 304
296 Just like the |:let| command, |:for| also accepts a list of variables. This 305 Just like the |:let| command, |:for| also accepts a list of variables. This
297 requires the argument to be a list of lists. > 306 requires the argument to be a list of lists. >
298 :for [lnum, col] in [[1, 3], [2, 8], [3, 0]] 307 :for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
299 : call Doit(lnum, col) 308 : call Doit(lnum, col)
300 :endfor 309 :endfor
301 310
302 This works like a |:let| command is done for each list item. Again, the types 311 This works like a |:let| command is done for each list item. Again, the types
303 must remain the same to avoid an error. 312 must remain the same to avoid an error.
304 313
305 It is also possible to put remaining items in a list: > 314 It is also possible to put remaining items in a List variable: >
306 :for [i, j; rest] in listlist 315 :for [i, j; rest] in listlist
307 : call Doit(i, j) 316 : call Doit(i, j)
308 : if !empty(rest) 317 : if !empty(rest)
309 : echo "remainder: " . string(rest) 318 : echo "remainder: " . string(rest)
310 : endif 319 : endif
311 :endfor 320 :endfor
312 321
313 322
314 List functions ~ 323 List functions ~
315 324 *E714*
316 Functions that are useful with a List: > 325 Functions that are useful with a List: >
317 :let r = call(funcname, list) " call a function with an argument list 326 :let r = call(funcname, list) " call a function with an argument list
318 :if empty(list) " check if list is empty 327 :if empty(list) " check if list is empty
319 :let l = len(list) " number of items in list 328 :let l = len(list) " number of items in list
320 :let big = max(list) " maximum value in list 329 :let big = max(list) " maximum value in list
328 :let s = string(list) " String representation of list 337 :let s = string(list) " String representation of list
329 :call map(list, '">> " . v:val') " prepend ">> " to each item 338 :call map(list, '">> " . v:val') " prepend ">> " to each item
330 339
331 340
332 1.4 Dictionaries ~ 341 1.4 Dictionaries ~
333 *Dictionaries* 342 *Dictionaries* *Dictionary*
334 A Dictionary is an associative array: Each entry has a key and a value. The 343 A Dictionary is an associative array: Each entry has a key and a value. The
335 entry can be located with the key. The entries are stored without ordering. 344 entry can be located with the key. The entries are stored without a specific
345 ordering.
336 346
337 347
338 Dictionary creation ~ 348 Dictionary creation ~
339 349 *E720* *E721* *E722* *E723*
340 A Dictionary is created with a comma separated list of entries in curly 350 A Dictionary is created with a comma separated list of entries in curly
341 braces. Each entry has a key and a value, separated by a colon. Examples: > 351 braces. Each entry has a key and a value, separated by a colon. Each key can
352 only appear once. Examples: >
342 :let mydict = {1: 'one', 2: 'two', 3: 'three'} 353 :let mydict = {1: 'one', 2: 'two', 3: 'three'}
343 :let emptydict = {} 354 :let emptydict = {}
344 355 < *E713* *E716* *E717*
345 A key is always a String. You can use a Number, it will be converted to a 356 A key is always a String. You can use a Number, it will be converted to a
346 String automatically. Thus the String '4' and the number 4 will find the same 357 String automatically. Thus the String '4' and the number 4 will find the same
347 entry. Note that the String '04' and the Number 04 are different, since 04 358 entry. Note that the String '04' and the Number 04 are different, since the
348 will be converted to the String '4'. 359 Number will be converted to the String '4'.
349 360
350 A value can be any expression. Using a Dictionary for an entry creates a 361 A value can be any expression. Using a Dictionary for a value creates a
351 nested Dictionary: > 362 nested Dictionary: >
352 :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}} 363 :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}}
353 364
354 An extra comma after the last entry is ignored. 365 An extra comma after the last entry is ignored.
355 366
358 369
359 The normal way to access an entry is by putting the key in square brackets: > 370 The normal way to access an entry is by putting the key in square brackets: >
360 :let val = mydict["one"] 371 :let val = mydict["one"]
361 :let mydict["four"] = 4 372 :let mydict["four"] = 4
362 373
363 You can add new entries to an existing Dictionary this way. 374 You can add new entries to an existing Dictionary this way, unlike Lists.
364 375
365 For keys that consist entirely of letters, digits and underscore the following 376 For keys that consist entirely of letters, digits and underscore the following
366 form can be used |expr-entry|: > 377 form can be used |expr-entry|: >
367 :let val = mydict.one 378 :let val = mydict.one
368 :let mydict.four = 4 379 :let mydict.four = 4
369 380
370 Since an entry can be any type, also a List and a Dictionary, the indexing and 381 Since an entry can be any type, also a List and a Dictionary, the indexing and
371 key lookup can be repeated: > 382 key lookup can be repeated: >
372 :let dict.key[idx].key = 0 383 :echo dict.key[idx].key
373 384
374 385
375 Dictionary to List conversion ~ 386 Dictionary to List conversion ~
376 387
377 You may want to loop over the entries in a dictionary. For this you need to 388 You may want to loop over the entries in a dictionary. For this you need to
389 :for v in values(mydict) 400 :for v in values(mydict)
390 : echo "value: " . v 401 : echo "value: " . v
391 :endfor 402 :endfor
392 403
393 If you want both the key and the value use the |items()| function. It returns 404 If you want both the key and the value use the |items()| function. It returns
394 a List of Lists with two items: the key and the value: > 405 a List in which each item is a List with two items, the key and the value: >
395 :for entry in items(mydict) 406 :for entry in items(mydict)
396 : echo entry[0] . ': ' . entry[1] 407 : echo entry[0] . ': ' . entry[1]
397 :endfor 408 :endfor
398 409
399 410
423 :let i = remove(dict, 'aaa') 434 :let i = remove(dict, 'aaa')
424 :unlet dict.aaa 435 :unlet dict.aaa
425 :unlet dict['aaa'] 436 :unlet dict['aaa']
426 437
427 Merging a Dictionary with another is done with |extend()|: > 438 Merging a Dictionary with another is done with |extend()|: >
428 :call extend(adict, bdict) " extend adict with entries from bdict 439 :call extend(adict, bdict)
440 This extends adict with all entries from bdict. Duplicate keys cause entries
441 in adict to be overwritten. An optional third argument can change this.
429 442
430 Weeding out entries from a Dictionary can be done with |filter()|: > 443 Weeding out entries from a Dictionary can be done with |filter()|: >
431 :call filter(dict 'v:val =~ "x"') " remove entries with value 'x' 444 :call filter(dict 'v:val =~ "x"')
445 This removes all entries from "dict" with a value not matching 'x'.
432 446
433 447
434 Dictionary function ~ 448 Dictionary function ~
435 *Dictionary-function* *self* 449 *Dictionary-function* *self* *E725*
436 When a function is defined with the "dict" attribute it can be used in a 450 When a function is defined with the "dict" attribute it can be used in a
437 special way with a dictionary. Example: > 451 special way with a dictionary. Example: >
438 :function Mylen() dict 452 :function Mylen() dict
439 : return len(self) - 4 453 : return len(self.data)
440 :endfunction 454 :endfunction
441 :let dict.len = function(Mylen) 455 :let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}
442 :let l = dict.len() 456 :echo mydict.len()
443 457
444 This is like a method in object oriented programming. The entry in the 458 This is like a method in object oriented programming. The entry in the
445 Dictionary is a |Funcref|. The local variable "self" refers to the dictionary 459 Dictionary is a |Funcref|. The local variable "self" refers to the dictionary
446 the function was invoked from. 460 the function was invoked from.
447 461
462 It is also possible to add a function without the "dict" attribute as a
463 Funcref to a Dictionary, but the "self" variable is not available then.
464
465 *numbered-function*
448 To avoid the extra name for the function it can be defined and directly 466 To avoid the extra name for the function it can be defined and directly
449 assigned to a Dictionary in this way: > 467 assigned to a Dictionary in this way: >
450 :function dict.len() dict 468 :let mydict = {'data': [0, 1, 2, 3]}
451 : return len(self) - 4 469 :function mydict.len() dict
470 : return len(self.data)
452 :endfunction 471 :endfunction
453 472 :echo mydict.len()
454 It is also possible to add a Funcref to a Dictionary without the "dict" 473
455 attribute, but the "self" variable is not available then. 474 The function will then get a number and the value of dict.len is a |Funcref|
475 that references this function. The function can only be used through a
476 |Funcref|. It will automatically be deleted when there is no |Funcref|
477 remaining that refers to it.
478
479 It is not necessary to use the "dict" attribute for a numbered function.
456 480
457 481
458 Functions for Dictionaries ~ 482 Functions for Dictionaries ~
459 483 *E715*
460 Functions that are useful with a Dictionary: > 484 Functions that can be used with a Dictionary: >
461 :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo" 485 :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo"
462 :if empty(dict) " TRUE if dict is empty 486 :if empty(dict) " TRUE if dict is empty
463 :let l = len(dict) " number of items in dict 487 :let l = len(dict) " number of items in dict
464 :let big = max(dict) " maximum value in dict 488 :let big = max(dict) " maximum value in dict
465 :let small = min(dict) " minimum value in dict 489 :let small = min(dict) " minimum value in dict
653 677
654 *E691* *E692* 678 *E691* *E692*
655 A List can only be compared with a List and only "equal", "not equal" and "is" 679 A List can only be compared with a List and only "equal", "not equal" and "is"
656 can be used. This compares the values of the list, recursively. Ignoring 680 can be used. This compares the values of the list, recursively. Ignoring
657 case means case is ignored when comparing item values. 681 case means case is ignored when comparing item values.
682
683 *E735* *E736*
684 A Dictionary can only be compared with a Dictionary and only "equal", "not
685 equal" and "is" can be used. This compares the key/values of the Dictionary,
686 recursively. Ignoring case means case is ignored when comparing item values.
658 687
659 *E693* *E694* 688 *E693* *E694*
660 A Funcref can only be compared with a Funcref and only "equal" and "not equal" 689 A Funcref can only be compared with a Funcref and only "equal" and "not equal"
661 can be used. Case is never ignored. 690 can be used. Case is never ignored.
662 691
1854 When {expr} is a List a full copy is created. This means 1883 When {expr} is a List a full copy is created. This means
1855 that the original List can be changed without changing the 1884 that the original List can be changed without changing the
1856 copy, and vise versa. When an item is a List, a copy for it 1885 copy, and vise versa. When an item is a List, a copy for it
1857 is made, recursively. Thus changing an item in the copy does 1886 is made, recursively. Thus changing an item in the copy does
1858 not change the contents of the original List. 1887 not change the contents of the original List.
1888 *E724*
1889 Nesting is possible up to 100 levels. When there is an item
1890 that refers back to a higher level making a deep copy will
1891 fail.
1859 Also see |copy()|. 1892 Also see |copy()|.
1860 1893
1861 delete({fname}) *delete()* 1894 delete({fname}) *delete()*
1862 Deletes the file by the name {fname}. The result is a Number, 1895 Deletes the file by the name {fname}. The result is a Number,
1863 which is 0 if the file was deleted successfully, and non-zero 1896 which is 0 if the file was deleted successfully, and non-zero
3050 let ind = indent(prevnonblank(v:lnum - 1)) 3083 let ind = indent(prevnonblank(v:lnum - 1))
3051 < When {lnum} is invalid or there is no non-blank line at or 3084 < When {lnum} is invalid or there is no non-blank line at or
3052 above it, zero is returned. 3085 above it, zero is returned.
3053 Also see |nextnonblank()|. 3086 Also see |nextnonblank()|.
3054 3087
3088 *E726* *E727*
3055 range({expr} [, {max} [, {stride}]]) *range()* 3089 range({expr} [, {max} [, {stride}]]) *range()*
3056 Returns a List with Numbers: 3090 Returns a List with Numbers:
3057 - If only {expr} is specified: [0, 1, ..., {expr} - 1] 3091 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
3058 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}] 3092 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
3059 - If {stride} is specified: [{expr}, {expr} + {stride}, ..., 3093 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
4011 4045
4012 *:fu* *:function* *E128* *E129* *E123* 4046 *:fu* *:function* *E128* *E129* *E123*
4013 :fu[nction] List all functions and their arguments. 4047 :fu[nction] List all functions and their arguments.
4014 4048
4015 :fu[nction] {name} List function {name}. 4049 :fu[nction] {name} List function {name}.
4016 *E124* *E125* 4050 {name} can also be a Dictionary entry that is a
4051 Funcref: >
4052 :function dict.init
4053 < *E124* *E125*
4017 :fu[nction][!] {name}([arguments]) [range] [abort] [dict] 4054 :fu[nction][!] {name}([arguments]) [range] [abort] [dict]
4018 Define a new function by the name {name}. The name 4055 Define a new function by the name {name}. The name
4019 must be made of alphanumeric characters and '_', and 4056 must be made of alphanumeric characters and '_', and
4020 must start with a capital or "s:" (see above). 4057 must start with a capital or "s:" (see above).
4058
4059 {name} can also be a Dictionary entry that is a
4060 Funcref: >
4061 :function dict.init(arg)
4062 < "dict" must be an existing dictionary. The entry
4063 "init" is added if it didn't exist yet. Otherwise [!]
4064 is required to overwrite an existing function. The
4065 result is a |Funcref| to a numbered function. The
4066 function can only be used with a |Funcref| and will be
4067 deleted if there are no more references to it.
4021 *function-argument* *a:var* 4068 *function-argument* *a:var*
4022 An argument can be defined by giving its name. In the 4069 An argument can be defined by giving its name. In the
4023 function this can then be used as "a:name" ("a:" for 4070 function this can then be used as "a:name" ("a:" for
4024 argument). 4071 argument).
4025 Up to 20 arguments can be given, separated by commas. 4072 Up to 20 arguments can be given, separated by commas.
4047 expected to take care of a range itself. The range is 4094 expected to take care of a range itself. The range is
4048 passed as "a:firstline" and "a:lastline". If [range] 4095 passed as "a:firstline" and "a:lastline". If [range]
4049 is excluded, ":{range}call" will call the function for 4096 is excluded, ":{range}call" will call the function for
4050 each line in the range, with the cursor on the start 4097 each line in the range, with the cursor on the start
4051 of each line. See |function-range-example|. 4098 of each line. See |function-range-example|.
4099
4052 When the [abort] argument is added, the function will 4100 When the [abort] argument is added, the function will
4053 abort as soon as an error is detected. 4101 abort as soon as an error is detected.
4054 The last used search pattern and the redo command "." 4102 The last used search pattern and the redo command "."
4055 will not be changed by the function. 4103 will not be changed by the function.
4104
4056 When the [dict] argument is added, the function must 4105 When the [dict] argument is added, the function must
4057 be invoked through an entry in a Dictionary. The 4106 be invoked through an entry in a Dictionary. The
4058 local variable "self" will then be set to the 4107 local variable "self" will then be set to the
4059 dictionary. See |Dictionary-function|. 4108 dictionary. See |Dictionary-function|.
4060 4109
4062 :endf[unction] The end of a function definition. Must be on a line 4111 :endf[unction] The end of a function definition. Must be on a line
4063 by its own, without other commands. 4112 by its own, without other commands.
4064 4113
4065 *:delf* *:delfunction* *E130* *E131* 4114 *:delf* *:delfunction* *E130* *E131*
4066 :delf[unction] {name} Delete function {name}. 4115 :delf[unction] {name} Delete function {name}.
4067 4116 {name} can also be a Dictionary entry that is a
4117 Funcref: >
4118 :delfunc dict.init
4119 < This will remove the "init" entry from "dict". The
4120 function is deleted if there are no more references to
4121 it.
4068 *:retu* *:return* *E133* 4122 *:retu* *:return* *E133*
4069 :retu[rn] [expr] Return from a function. When "[expr]" is given, it is 4123 :retu[rn] [expr] Return from a function. When "[expr]" is given, it is
4070 evaluated and returned as the result of the function. 4124 evaluated and returned as the result of the function.
4071 If "[expr]" is not given, the number 0 is returned. 4125 If "[expr]" is not given, the number 0 is returned.
4072 When a function ends without an explicit ":return", 4126 When a function ends without an explicit ":return",
4236 {expr1}. {var-name} must refer to a list and {idx} 4290 {expr1}. {var-name} must refer to a list and {idx}
4237 must be a valid index in that list. For nested list 4291 must be a valid index in that list. For nested list
4238 the index can be repeated. 4292 the index can be repeated.
4239 This cannot be used to add an item to a list. 4293 This cannot be used to add an item to a list.
4240 4294
4241 :let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710* *E711* 4295 *E711* *E719*
4296 :let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710*
4242 Set a sequence of items in a List to the result of the 4297 Set a sequence of items in a List to the result of the
4243 expression {expr1}, which must be a list with the 4298 expression {expr1}, which must be a list with the
4244 correct number of items. 4299 correct number of items.
4245 {idx1} can be omitted, zero is used instead. 4300 {idx1} can be omitted, zero is used instead.
4246 {idx2} can be omitted, meaning the end of the list. 4301 {idx2} can be omitted, meaning the end of the list.
4247 When the selected range of items is partly past the 4302 When the selected range of items is partly past the
4248 end of the list, items will be added. 4303 end of the list, items will be added.
4249 4304
4305 :let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
4306 :let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
4307 :let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
4308 These fail if {var} was not set yet and when the type
4309 of {var} and {expr1} don't fit the operator.
4310
4311
4250 :let ${env-name} = {expr1} *:let-environment* *:let-$* 4312 :let ${env-name} = {expr1} *:let-environment* *:let-$*
4251 Set environment variable {env-name} to the result of 4313 Set environment variable {env-name} to the result of
4252 the expression {expr1}. The type is always String. 4314 the expression {expr1}. The type is always String.
4315 :let ${env-name} .= {expr1}
4316 Append {expr1} to the environment variable {env-name}.
4317 If the environment variable didn't exist yet this
4318 works like "=".
4253 4319
4254 :let @{reg-name} = {expr1} *:let-register* *:let-@* 4320 :let @{reg-name} = {expr1} *:let-register* *:let-@*
4255 Write the result of the expression {expr1} in register 4321 Write the result of the expression {expr1} in register
4256 {reg-name}. {reg-name} must be a single letter, and 4322 {reg-name}. {reg-name} must be a single letter, and
4257 must be the name of a writable register (see 4323 must be the name of a writable register (see
4263 This can be used to clear the last search pattern: > 4329 This can be used to clear the last search pattern: >
4264 :let @/ = "" 4330 :let @/ = ""
4265 < This is different from searching for an empty string, 4331 < This is different from searching for an empty string,
4266 that would match everywhere. 4332 that would match everywhere.
4267 4333
4334 :let @{reg-name} .= {expr1}
4335 Append {expr1} to register {reg-name}. If the
4336 register was empty it's like setting it to {expr1}.
4337
4268 :let &{option-name} = {expr1} *:let-option* *:let-star* 4338 :let &{option-name} = {expr1} *:let-option* *:let-star*
4269 Set option {option-name} to the result of the 4339 Set option {option-name} to the result of the
4270 expression {expr1}. A String or Number value is 4340 expression {expr1}. A String or Number value is
4271 always converted to the type of the option. 4341 always converted to the type of the option.
4272 For an option local to a window or buffer the effect 4342 For an option local to a window or buffer the effect
4273 is just like using the |:set| command: both the local 4343 is just like using the |:set| command: both the local
4274 value and the global value is changed. 4344 value and the global value is changed.
4275 Example: > 4345 Example: >
4276 :let &path = &path . ',/usr/local/include' 4346 :let &path = &path . ',/usr/local/include'
4277 4347
4348 :let &{option-name} .= {expr1}
4349 For a string option: Append {expr1} to the value.
4350 Does not insert a comma like |:set+=|.
4351
4352 :let &{option-name} += {expr1}
4353 :let &{option-name} -= {expr1}
4354 For a number or boolean option: Add or subtract
4355 {expr1}.
4356
4278 :let &l:{option-name} = {expr1} 4357 :let &l:{option-name} = {expr1}
4358 :let &l:{option-name} .= {expr1}
4359 :let &l:{option-name} += {expr1}
4360 :let &l:{option-name} -= {expr1}
4279 Like above, but only set the local value of an option 4361 Like above, but only set the local value of an option
4280 (if there is one). Works like |:setlocal|. 4362 (if there is one). Works like |:setlocal|.
4281 4363
4282 :let &g:{option-name} = {expr1} 4364 :let &g:{option-name} = {expr1}
4365 :let &g:{option-name} .= {expr1}
4366 :let &g:{option-name} += {expr1}
4367 :let &g:{option-name} -= {expr1}
4283 Like above, but only set the global value of an option 4368 Like above, but only set the global value of an option
4284 (if there is one). Works like |:setglobal|. 4369 (if there is one). Works like |:setglobal|.
4285 4370
4286 :let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688* 4371 :let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
4287 {expr1} must evaluate to a List. The first item in 4372 {expr1} must evaluate to a List. The first item in
4291 the List. 4376 the List.
4292 Each name can be one of the items of the ":let" 4377 Each name can be one of the items of the ":let"
4293 command as mentioned above. 4378 command as mentioned above.
4294 Example: > 4379 Example: >
4295 :let [s, item] = GetItem(s) 4380 :let [s, item] = GetItem(s)
4381 < Detail: {expr1} is evaluated first, then the
4382 assignments are done in sequence. This matters if
4383 {name2} depends on {name1}. Example: >
4384 :let x = [0, 1]
4385 :let i = 0
4386 :let [i, x[i]] = [1, 2]
4387 :echo x
4388 < The result is [0, 2].
4389
4390 :let [{name1}, {name2}, ...] .= {expr1}
4391 :let [{name1}, {name2}, ...] += {expr1}
4392 :let [{name1}, {name2}, ...] -= {expr1}
4393 Like above, but append/add/subtract the value for each
4394 List item.
4296 4395
4297 :let [{name}, ..., ; {lastname}] = {expr1} 4396 :let [{name}, ..., ; {lastname}] = {expr1}
4298 Like above, but the List may have more items than 4397 Like |let-unpack| above, but the List may have more
4299 there are names. A list of the remaining items is 4398 items than there are names. A list of the remaining
4300 assigned to {lastname}. If there are no remaining 4399 items is assigned to {lastname}. If there are no
4301 items {lastname} is set to an empty list. 4400 remaining items {lastname} is set to an empty list.
4302 Example: > 4401 Example: >
4303 :let [a, b; rest] = ["aval", "bval", 3, 4] 4402 :let [a, b; rest] = ["aval", "bval", 3, 4]
4304 < 4403 <
4404 :let [{name}, ..., ; {lastname}] .= {expr1}
4405 :let [{name}, ..., ; {lastname}] += {expr1}
4406 :let [{name}, ..., ; {lastname}] -= {expr1}
4407 Like above, but append/add/subtract the value for each
4408 List item.
4305 *E106* 4409 *E106*
4306 :let {var-name} .. List the value of variable {var-name}. Several 4410 :let {var-name} .. List the value of variable {var-name}. Multiple
4307 variable names may be given. 4411 variable names may be given.
4308 4412
4309 :let List the values of all variables. The type of the 4413 :let List the values of all variables. The type of the
4310 variable is indicated before the value: 4414 variable is indicated before the value:
4311 <nothing> String 4415 <nothing> String
4361 *:elseif* *:elsei* *E582* *E584* 4465 *:elseif* *:elsei* *E582* *E584*
4362 :elsei[f] {expr1} Short for ":else" ":if", with the addition that there 4466 :elsei[f] {expr1} Short for ":else" ":if", with the addition that there
4363 is no extra ":endif". 4467 is no extra ":endif".
4364 4468
4365 :wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw* 4469 :wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw*
4366 *E170* *E585* *E588* 4470 *E170* *E585* *E588* *E733*
4367 :endw[hile] Repeat the commands between ":while" and ":endwhile", 4471 :endw[hile] Repeat the commands between ":while" and ":endwhile",
4368 as long as {expr1} evaluates to non-zero. 4472 as long as {expr1} evaluates to non-zero.
4369 When an error is detected from a command inside the 4473 When an error is detected from a command inside the
4370 loop, execution continues after the "endwhile". 4474 loop, execution continues after the "endwhile".
4371 Example: > 4475 Example: >
4376 :endwhile 4480 :endwhile
4377 < 4481 <
4378 NOTE: The ":append" and ":insert" commands don't work 4482 NOTE: The ":append" and ":insert" commands don't work
4379 properly inside a ":while" and ":for" loop. 4483 properly inside a ":while" and ":for" loop.
4380 4484
4381 :for {var} in {list} *:for* *E690* 4485 :for {var} in {list} *:for* *E690* *E732*
4382 :endfo[r] *:endfo* *:endfor* 4486 :endfo[r] *:endfo* *:endfor*
4383 Repeat the commands between ":for" and ":endfor" for 4487 Repeat the commands between ":for" and ":endfor" for
4384 each item in {list}. variable {var} is set to the 4488 each item in {list}. variable {var} is set to the
4385 value of each item. 4489 value of each item.
4386 When an error is detected for a command inside the 4490 When an error is detected for a command inside the