| blob | 157df6dd0df214e1c0d3bd10f667e4785abe93d2 |
1 *eval.txt* For Vim version 7.1. Last change: 2008 Jun 19
4 VIM REFERENCE MANUAL by Bram Moolenaar
7 Expression evaluation *expression* *expr* *E15* *eval*
9 Using expressions is introduced in chapter 41 of the user manual |usr_41.txt|.
11 Note: Expression evaluation can be disabled at compile time. If this has been
12 done, the features in this document are not available. See |+eval| and
13 |no-eval-feature|.
15 1. Variables |variables|
16 1.1 Variable types
17 1.2 Function references |Funcref|
18 1.3 Lists |Lists|
19 1.4 Dictionaries |Dictionaries|
20 1.5 More about variables |more-variables|
21 2. Expression syntax |expression-syntax|
22 3. Internal variable |internal-variables|
23 4. Builtin Functions |functions|
24 5. Defining functions |user-functions|
25 6. Curly braces names |curly-braces-names|
26 7. Commands |expression-commands|
27 8. Exception handling |exception-handling|
28 9. Examples |eval-examples|
29 10. No +eval feature |no-eval-feature|
30 11. The sandbox |eval-sandbox|
31 12. Textlock |textlock|
33 {Vi does not have any of these commands}
35 ==============================================================================
36 1. Variables *variables*
38 1.1 Variable types ~
39 *E712*
40 There are six types of variables:
42 Number A 32 bit signed number. |expr-number| *Number*
43 Examples: -123 0x10 0177
45 Float A floating point number. |floating-point-format| *Float*
46 {only when compiled with the |+float| feature}
47 Examples: 123.456 1.15e-6 -1.1e3
49 String A NUL terminated string of 8-bit unsigned characters (bytes).
50 |expr-string| Examples: "ab\txx\"--" 'x-z''a,c'
52 Funcref A reference to a function |Funcref|.
53 Example: function("strlen")
55 List An ordered sequence of items |List|.
56 Example: [1, 2, ['a', 'b']]
58 Dictionary An associative, unordered array: Each entry has a key and a
59 value. |Dictionary|
60 Example: {'blue': "#0000ff", 'red': "#ff0000"}
62 The Number and String types are converted automatically, depending on how they
63 are used.
65 Conversion from a Number to a String is by making the ASCII representation of
66 the Number. Examples: >
67 Number 123 --> String "123"
68 Number 0 --> String "0"
69 Number -1 --> String "-1"
71 Conversion from a String to a Number is done by converting the first digits
72 to a number. Hexadecimal "0xf9" and Octal "017" numbers are recognized. If
73 the String doesn't start with digits, the result is zero. Examples: >
74 String "456" --> Number 456
75 String "6bar" --> Number 6
76 String "foo" --> Number 0
77 String "0xf1" --> Number 241
78 String "0100" --> Number 64
79 String "-8" --> Number -8
80 String "+8" --> Number 0
82 To force conversion from String to Number, add zero to it: >
83 :echo "0100" + 0
84 < 64 ~
86 To avoid a leading zero to cause octal conversion, or for using a different
87 base, use |str2nr()|.
89 For boolean operators Numbers are used. Zero is FALSE, non-zero is TRUE.
91 Note that in the command >
92 :if "foo"
93 "foo" is converted to 0, which means FALSE. To test for a non-empty string,
94 use strlen(): >
95 :if strlen("foo")
96 < *E745* *E728* *E703* *E729* *E730* *E731*
97 List, Dictionary and Funcref types are not automatically converted.
99 *E805* *E806* *E808*
100 When mixing Number and Float the Number is converted to Float. Otherwise
101 there is no automatic conversion of Float. You can use str2float() for String
102 to Float, printf() for Float to String and float2nr() for Float to Number.
104 *E706*
105 You will get an error if you try to change the type of a variable. You need
106 to |:unlet| it first to avoid this error. String and Number are considered
107 equivalent though. Consider this sequence of commands: >
108 :let l = "string"
109 :let l = 44 " changes type from String to Number
110 :let l = [1, 2, 3] " error!
113 1.2 Function references ~
114 *Funcref* *E695* *E718*
115 A Funcref variable is obtained with the |function()| function. It can be used
116 in an expression in the place of a function name, before the parenthesis
117 around the arguments, to invoke the function it refers to. Example: >
119 :let Fn = function("MyFunc")
120 :echo Fn()
121 < *E704* *E705* *E707*
122 A Funcref variable must start with a capital, "s:", "w:", "t:" or "b:". You
123 cannot have both a Funcref variable and a function with the same name.
125 A special case is defining a function and directly assigning its Funcref to a
126 Dictionary entry. Example: >
127 :function dict.init() dict
128 : let self.val = 0
129 :endfunction
131 The key of the Dictionary can start with a lower case letter. The actual
132 function name is not used here. Also see |numbered-function|.
134 A Funcref can also be used with the |:call| command: >
135 :call Fn()
136 :call dict.init()
138 The name of the referenced function can be obtained with |string()|. >
139 :let func = string(Fn)
141 You can use |call()| to invoke a Funcref and use a list variable for the
142 arguments: >
143 :let r = call(Fn, mylist)
146 1.3 Lists ~
147 *List* *Lists* *E686*
148 A List is an ordered sequence of items. An item can be of any type. Items
149 can be accessed by their index number. Items can be added and removed at any
150 position in the sequence.
153 List creation ~
154 *E696* *E697*
155 A List is created with a comma separated list of items in square brackets.
156 Examples: >
157 :let mylist = [1, two, 3, "four"]
158 :let emptylist = []
160 An item can be any expression. Using a List for an item creates a
161 List of Lists: >
162 :let nestlist = [[11, 12], [21, 22], [31, 32]]
164 An extra comma after the last item is ignored.
167 List index ~
168 *list-index* *E684*
169 An item in the List can be accessed by putting the index in square brackets
170 after the List. Indexes are zero-based, thus the first item has index zero. >
171 :let item = mylist[0] " get the first item: 1
172 :let item = mylist[2] " get the third item: 3
174 When the resulting item is a list this can be repeated: >
175 :let item = nestlist[0][1] " get the first list, second item: 12
176 <
177 A negative index is counted from the end. Index -1 refers to the last item in
178 the List, -2 to the last but one item, etc. >
179 :let last = mylist[-1] " get the last item: "four"
181 To avoid an error for an invalid index use the |get()| function. When an item
182 is not available it returns zero or the default value you specify: >
183 :echo get(mylist, idx)
184 :echo get(mylist, idx, "NONE")
187 List concatenation ~
189 Two lists can be concatenated with the "+" operator: >
190 :let longlist = mylist + [5, 6]
191 :let mylist += [7, 8]
193 To prepend or append an item turn the item into a list by putting [] around
194 it. To change a list in-place see |list-modification| below.
197 Sublist ~
199 A part of the List can be obtained by specifying the first and last index,
200 separated by a colon in square brackets: >
201 :let shortlist = mylist[2:-1] " get List [3, "four"]
203 Omitting the first index is similar to zero. Omitting the last index is
204 similar to -1. >
205 :let endlist = mylist[2:] " from item 2 to the end: [3, "four"]
206 :let shortlist = mylist[2:2] " List with one item: [3]
207 :let otherlist = mylist[:] " make a copy of the List
209 If the first index is beyond the last item of the List or the second item is
210 before the first item, the result is an empty list. There is no error
211 message.
213 If the second index is equal to or greater than the length of the list the
214 length minus one is used: >
215 :let mylist = [0, 1, 2, 3]
216 :echo mylist[2:8] " result: [2, 3]
218 NOTE: mylist[s:e] means using the variable "s:e" as index. Watch out for
219 using a single letter variable before the ":". Insert a space when needed:
220 mylist[s : e].
223 List identity ~
224 *list-identity*
225 When variable "aa" is a list and you assign it to another variable "bb", both
226 variables refer to the same list. Thus changing the list "aa" will also
227 change "bb": >
228 :let aa = [1, 2, 3]
229 :let bb = aa
230 :call add(aa, 4)
231 :echo bb
232 < [1, 2, 3, 4]
234 Making a copy of a list is done with the |copy()| function. Using [:] also
235 works, as explained above. This creates a shallow copy of the list: Changing
236 a list item in the list will also change the item in the copied list: >
237 :let aa = [[1, 'a'], 2, 3]
238 :let bb = copy(aa)
239 :call add(aa, 4)
240 :let aa[0][1] = 'aaa'
241 :echo aa
242 < [[1, aaa], 2, 3, 4] >
243 :echo bb
244 < [[1, aaa], 2, 3]
246 To make a completely independent list use |deepcopy()|. This also makes a
247 copy of the values in the list, recursively. Up to a hundred levels deep.
249 The operator "is" can be used to check if two variables refer to the same
250 List. "isnot" does the opposite. In contrast "==" compares if two lists have
251 the same value. >
252 :let alist = [1, 2, 3]
253 :let blist = [1, 2, 3]
254 :echo alist is blist
255 < 0 >
256 :echo alist == blist
257 < 1
259 Note about comparing lists: Two lists are considered equal if they have the
260 same length and all items compare equal, as with using "==". There is one
261 exception: When comparing a number with a string they are considered
262 different. There is no automatic type conversion, as with using "==" on
263 variables. Example: >
264 echo 4 == "4"
265 < 1 >
266 echo [4] == ["4"]
267 < 0
269 Thus comparing Lists is more strict than comparing numbers and strings. You
270 can compare simple values this way too by putting them in a list: >
272 :let a = 5
273 :let b = "5"
274 :echo a == b
275 < 1 >
276 :echo [a] == [b]
277 < 0
280 List unpack ~
282 To unpack the items in a list to individual variables, put the variables in
283 square brackets, like list items: >
284 :let [var1, var2] = mylist
286 When the number of variables does not match the number of items in the list
287 this produces an error. To handle any extra items from the list append ";"
288 and a variable name: >
289 :let [var1, var2; rest] = mylist
291 This works like: >
292 :let var1 = mylist[0]
293 :let var2 = mylist[1]
294 :let rest = mylist[2:]
296 Except that there is no error if there are only two items. "rest" will be an
297 empty list then.
300 List modification ~
301 *list-modification*
302 To change a specific item of a list use |:let| this way: >
303 :let list[4] = "four"
304 :let listlist[0][3] = item
306 To change part of a list you can specify the first and last item to be
307 modified. The value must at least have the number of items in the range: >
308 :let list[3:5] = [3, 4, 5]
310 Adding and removing items from a list is done with functions. Here are a few
311 examples: >
312 :call insert(list, 'a') " prepend item 'a'
313 :call insert(list, 'a', 3) " insert item 'a' before list[3]
314 :call add(list, "new") " append String item
315 :call add(list, [1, 2]) " append a List as one new item
316 :call extend(list, [1, 2]) " extend the list with two more items
317 :let i = remove(list, 3) " remove item 3
318 :unlet list[3] " idem
319 :let l = remove(list, 3, -1) " remove items 3 to last item
320 :unlet list[3 : ] " idem
321 :call filter(list, 'v:val !~ "x"') " remove items with an 'x'
323 Changing the order of items in a list: >
324 :call sort(list) " sort a list alphabetically
325 :call reverse(list) " reverse the order of items
328 For loop ~
330 The |:for| loop executes commands for each item in a list. A variable is set
331 to each item in the list in sequence. Example: >
332 :for item in mylist
333 : call Doit(item)
334 :endfor
336 This works like: >
337 :let index = 0
338 :while index < len(mylist)
339 : let item = mylist[index]
340 : :call Doit(item)
341 : let index = index + 1
342 :endwhile
344 Note that all items in the list should be of the same type, otherwise this
345 results in error |E706|. To avoid this |:unlet| the variable at the end of
346 the loop.
348 If all you want to do is modify each item in the list then the |map()|
349 function will be a simpler method than a for loop.
351 Just like the |:let| command, |:for| also accepts a list of variables. This
352 requires the argument to be a list of lists. >
353 :for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
354 : call Doit(lnum, col)
355 :endfor
357 This works like a |:let| command is done for each list item. Again, the types
358 must remain the same to avoid an error.
360 It is also possible to put remaining items in a List variable: >
361 :for [i, j; rest] in listlist
362 : call Doit(i, j)
363 : if !empty(rest)
364 : echo "remainder: " . string(rest)
365 : endif
366 :endfor
369 List functions ~
370 *E714*
371 Functions that are useful with a List: >
372 :let r = call(funcname, list) " call a function with an argument list
373 :if empty(list) " check if list is empty
374 :let l = len(list) " number of items in list
375 :let big = max(list) " maximum value in list
376 :let small = min(list) " minimum value in list
377 :let xs = count(list, 'x') " count nr of times 'x' appears in list
378 :let i = index(list, 'x') " index of first 'x' in list
379 :let lines = getline(1, 10) " get ten text lines from buffer
380 :call append('$', lines) " append text lines in buffer
381 :let list = split("a b c") " create list from items in a string
382 :let string = join(list, ', ') " create string from list items
383 :let s = string(list) " String representation of list
384 :call map(list, '">> " . v:val') " prepend ">> " to each item
386 Don't forget that a combination of features can make things simple. For
387 example, to add up all the numbers in a list: >
388 :exe 'let sum = ' . join(nrlist, '+')
391 1.4 Dictionaries ~
392 *Dictionaries* *Dictionary*
393 A Dictionary is an associative array: Each entry has a key and a value. The
394 entry can be located with the key. The entries are stored without a specific
395 ordering.
398 Dictionary creation ~
399 *E720* *E721* *E722* *E723*
400 A Dictionary is created with a comma separated list of entries in curly
401 braces. Each entry has a key and a value, separated by a colon. Each key can
402 only appear once. Examples: >
403 :let mydict = {1: 'one', 2: 'two', 3: 'three'}
404 :let emptydict = {}
405 < *E713* *E716* *E717*
406 A key is always a String. You can use a Number, it will be converted to a
407 String automatically. Thus the String '4' and the number 4 will find the same
408 entry. Note that the String '04' and the Number 04 are different, since the
409 Number will be converted to the String '4'.
411 A value can be any expression. Using a Dictionary for a value creates a
412 nested Dictionary: >
413 :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}}
415 An extra comma after the last entry is ignored.
418 Accessing entries ~
420 The normal way to access an entry is by putting the key in square brackets: >
421 :let val = mydict["one"]
422 :let mydict["four"] = 4
424 You can add new entries to an existing Dictionary this way, unlike Lists.
426 For keys that consist entirely of letters, digits and underscore the following
427 form can be used |expr-entry|: >
428 :let val = mydict.one
429 :let mydict.four = 4
431 Since an entry can be any type, also a List and a Dictionary, the indexing and
432 key lookup can be repeated: >
433 :echo dict.key[idx].key
436 Dictionary to List conversion ~
438 You may want to loop over the entries in a dictionary. For this you need to
439 turn the Dictionary into a List and pass it to |:for|.
441 Most often you want to loop over the keys, using the |keys()| function: >
442 :for key in keys(mydict)
443 : echo key . ': ' . mydict[key]
444 :endfor
446 The List of keys is unsorted. You may want to sort them first: >
447 :for key in sort(keys(mydict))
449 To loop over the values use the |values()| function: >
450 :for v in values(mydict)
451 : echo "value: " . v
452 :endfor
454 If you want both the key and the value use the |items()| function. It returns
455 a List in which each item is a List with two items, the key and the value: >
456 :for [key, value] in items(mydict)
457 : echo key . ': ' . value
458 :endfor
461 Dictionary identity ~
462 *dict-identity*
463 Just like Lists you need to use |copy()| and |deepcopy()| to make a copy of a
464 Dictionary. Otherwise, assignment results in referring to the same
465 Dictionary: >
466 :let onedict = {'a': 1, 'b': 2}
467 :let adict = onedict
468 :let adict['a'] = 11
469 :echo onedict['a']
470 11
472 Two Dictionaries compare equal if all the key-value pairs compare equal. For
473 more info see |list-identity|.
476 Dictionary modification ~
477 *dict-modification*
478 To change an already existing entry of a Dictionary, or to add a new entry,
479 use |:let| this way: >
480 :let dict[4] = "four"
481 :let dict['one'] = item
483 Removing an entry from a Dictionary is done with |remove()| or |:unlet|.
484 Three ways to remove the entry with key "aaa" from dict: >
485 :let i = remove(dict, 'aaa')
486 :unlet dict.aaa
487 :unlet dict['aaa']
489 Merging a Dictionary with another is done with |extend()|: >
490 :call extend(adict, bdict)
491 This extends adict with all entries from bdict. Duplicate keys cause entries
492 in adict to be overwritten. An optional third argument can change this.
493 Note that the order of entries in a Dictionary is irrelevant, thus don't
494 expect ":echo adict" to show the items from bdict after the older entries in
495 adict.
497 Weeding out entries from a Dictionary can be done with |filter()|: >
498 :call filter(dict, 'v:val =~ "x"')
499 This removes all entries from "dict" with a value not matching 'x'.
502 Dictionary function ~
503 *Dictionary-function* *self* *E725*
504 When a function is defined with the "dict" attribute it can be used in a
505 special way with a dictionary. Example: >
506 :function Mylen() dict
507 : return len(self.data)
508 :endfunction
509 :let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}
510 :echo mydict.len()
512 This is like a method in object oriented programming. The entry in the
513 Dictionary is a |Funcref|. The local variable "self" refers to the dictionary
514 the function was invoked from.
516 It is also possible to add a function without the "dict" attribute as a
517 Funcref to a Dictionary, but the "self" variable is not available then.
519 *numbered-function* *anonymous-function*
520 To avoid the extra name for the function it can be defined and directly
521 assigned to a Dictionary in this way: >
522 :let mydict = {'data': [0, 1, 2, 3]}
523 :function mydict.len() dict
524 : return len(self.data)
525 :endfunction
526 :echo mydict.len()
528 The function will then get a number and the value of dict.len is a |Funcref|
529 that references this function. The function can only be used through a
530 |Funcref|. It will automatically be deleted when there is no |Funcref|
531 remaining that refers to it.
533 It is not necessary to use the "dict" attribute for a numbered function.
536 Functions for Dictionaries ~
537 *E715*
538 Functions that can be used with a Dictionary: >
539 :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo"
540 :if empty(dict) " TRUE if dict is empty
541 :let l = len(dict) " number of items in dict
542 :let big = max(dict) " maximum value in dict
543 :let small = min(dict) " minimum value in dict
544 :let xs = count(dict, 'x') " count nr of times 'x' appears in dict
545 :let s = string(dict) " String representation of dict
546 :call map(dict, '">> " . v:val') " prepend ">> " to each item
549 1.5 More about variables ~
550 *more-variables*
551 If you need to know the type of a variable or expression, use the |type()|
552 function.
554 When the '!' flag is included in the 'viminfo' option, global variables that
555 start with an uppercase letter, and don't contain a lowercase letter, are
556 stored in the viminfo file |viminfo-file|.
558 When the 'sessionoptions' option contains "global", global variables that
559 start with an uppercase letter and contain at least one lowercase letter are
560 stored in the session file |session-file|.
562 variable name can be stored where ~
563 my_var_6 not
564 My_Var_6 session file
565 MY_VAR_6 viminfo file
568 It's possible to form a variable name with curly braces, see
569 |curly-braces-names|.
571 ==============================================================================
572 2. Expression syntax *expression-syntax*
574 Expression syntax summary, from least to most significant:
576 |expr1| expr2 ? expr1 : expr1 if-then-else
578 |expr2| expr3 || expr3 .. logical OR
580 |expr3| expr4 && expr4 .. logical AND
582 |expr4| expr5 == expr5 equal
583 expr5 != expr5 not equal
584 expr5 > expr5 greater than
585 expr5 >= expr5 greater than or equal
586 expr5 < expr5 smaller than
587 expr5 <= expr5 smaller than or equal
588 expr5 =~ expr5 regexp matches
589 expr5 !~ expr5 regexp doesn't match
591 expr5 ==? expr5 equal, ignoring case
592 expr5 ==# expr5 equal, match case
593 etc. As above, append ? for ignoring case, # for
594 matching case
596 expr5 is expr5 same |List| instance
597 expr5 isnot expr5 different |List| instance
599 |expr5| expr6 + expr6 .. number addition or list concatenation
600 expr6 - expr6 .. number subtraction
601 expr6 . expr6 .. string concatenation
603 |expr6| expr7 * expr7 .. number multiplication
604 expr7 / expr7 .. number division
605 expr7 % expr7 .. number modulo
607 |expr7| ! expr7 logical NOT
608 - expr7 unary minus
609 + expr7 unary plus
612 |expr8| expr8[expr1] byte of a String or item of a |List|
613 expr8[expr1 : expr1] substring of a String or sublist of a |List|
614 expr8.name entry in a |Dictionary|
615 expr8(expr1, ...) function call with |Funcref| variable
617 |expr9| number number constant
618 "string" string constant, backslash is special
619 'string' string constant, ' is doubled
620 [expr1, ...] |List|
621 {expr1: expr1, ...} |Dictionary|
622 &option option value
623 (expr1) nested expression
624 variable internal variable
625 va{ria}ble internal variable with curly braces
626 $VAR environment variable
627 @r contents of register 'r'
628 function(expr1, ...) function call
629 func{ti}on(expr1, ...) function call with curly braces
632 ".." indicates that the operations in this level can be concatenated.
633 Example: >
634 &nu || &list && &shell == "csh"
636 All expressions within one level are parsed from left to right.
639 expr1 *expr1* *E109*
640 -----
642 expr2 ? expr1 : expr1
644 The expression before the '?' is evaluated to a number. If it evaluates to
645 non-zero, the result is the value of the expression between the '?' and ':',
646 otherwise the result is the value of the expression after the ':'.
647 Example: >
648 :echo lnum == 1 ? "top" : lnum
650 Since the first expression is an "expr2", it cannot contain another ?:. The
651 other two expressions can, thus allow for recursive use of ?:.
652 Example: >
653 :echo lnum == 1 ? "top" : lnum == 1000 ? "last" : lnum
655 To keep this readable, using |line-continuation| is suggested: >
656 :echo lnum == 1
657 :\ ? "top"
658 :\ : lnum == 1000
659 :\ ? "last"
660 :\ : lnum
662 You should always put a space before the ':', otherwise it can be mistaken for
663 use in a variable such as "a:1".
666 expr2 and expr3 *expr2* *expr3*
667 ---------------
669 *expr-barbar* *expr-&&*
670 The "||" and "&&" operators take one argument on each side. The arguments
671 are (converted to) Numbers. The result is:
673 input output ~
674 n1 n2 n1 || n2 n1 && n2 ~
675 zero zero zero zero
676 zero non-zero non-zero zero
677 non-zero zero non-zero zero
678 non-zero non-zero non-zero non-zero
680 The operators can be concatenated, for example: >
682 &nu || &list && &shell == "csh"
684 Note that "&&" takes precedence over "||", so this has the meaning of: >
686 &nu || (&list && &shell == "csh")
688 Once the result is known, the expression "short-circuits", that is, further
689 arguments are not evaluated. This is like what happens in C. For example: >
691 let a = 1
692 echo a || b
694 This is valid even if there is no variable called "b" because "a" is non-zero,
695 so the result must be non-zero. Similarly below: >
697 echo exists("b") && b == "yes"
699 This is valid whether "b" has been defined or not. The second clause will
700 only be evaluated if "b" has been defined.
703 expr4 *expr4*
704 -----
706 expr5 {cmp} expr5
708 Compare two expr5 expressions, resulting in a 0 if it evaluates to false, or 1
709 if it evaluates to true.
711 *expr-==* *expr-!=* *expr->* *expr->=*
712 *expr-<* *expr-<=* *expr-=~* *expr-!~*
713 *expr-==#* *expr-!=#* *expr->#* *expr->=#*
714 *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#*
715 *expr-==?* *expr-!=?* *expr->?* *expr->=?*
716 *expr-<?* *expr-<=?* *expr-=~?* *expr-!~?*
717 *expr-is*
718 use 'ignorecase' match case ignore case ~
719 equal == ==# ==?
720 not equal != !=# !=?
721 greater than > ># >?
722 greater than or equal >= >=# >=?
723 smaller than < <# <?
724 smaller than or equal <= <=# <=?
725 regexp matches =~ =~# =~?
726 regexp doesn't match !~ !~# !~?
727 same instance is
728 different instance isnot
730 Examples:
731 "abc" ==# "Abc" evaluates to 0
732 "abc" ==? "Abc" evaluates to 1
733 "abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise
735 *E691* *E692*
736 A |List| can only be compared with a |List| and only "equal", "not equal" and
737 "is" can be used. This compares the values of the list, recursively.
738 Ignoring case means case is ignored when comparing item values.
740 *E735* *E736*
741 A |Dictionary| can only be compared with a |Dictionary| and only "equal", "not
742 equal" and "is" can be used. This compares the key/values of the |Dictionary|
743 recursively. Ignoring case means case is ignored when comparing item values.
745 *E693* *E694*
746 A |Funcref| can only be compared with a |Funcref| and only "equal" and "not
747 equal" can be used. Case is never ignored.
749 When using "is" or "isnot" with a |List| this checks if the expressions are
750 referring to the same |List| instance. A copy of a |List| is different from
751 the original |List|. When using "is" without a |List| it is equivalent to
752 using "equal", using "isnot" equivalent to using "not equal". Except that a
753 different type means the values are different. "4 == '4'" is true, "4 is '4'"
754 is false.
756 When comparing a String with a Number, the String is converted to a Number,
757 and the comparison is done on Numbers. This means that "0 == 'x'" is TRUE,
758 because 'x' converted to a Number is zero.
760 When comparing two Strings, this is done with strcmp() or stricmp(). This
761 results in the mathematical difference (comparing byte values), not
762 necessarily the alphabetical difference in the local language.
764 When using the operators with a trailing '#', or the short version and
765 'ignorecase' is off, the comparing is done with strcmp(): case matters.
767 When using the operators with a trailing '?', or the short version and
768 'ignorecase' is set, the comparing is done with stricmp(): case is ignored.
770 'smartcase' is not used.
772 The "=~" and "!~" operators match the lefthand argument with the righthand
773 argument, which is used as a pattern. See |pattern| for what a pattern is.
774 This matching is always done like 'magic' was set and 'cpoptions' is empty, no
775 matter what the actual value of 'magic' or 'cpoptions' is. This makes scripts
776 portable. To avoid backslashes in the regexp pattern to be doubled, use a
777 single-quote string, see |literal-string|.
778 Since a string is considered to be a single line, a multi-line pattern
779 (containing \n, backslash-n) will not match. However, a literal NL character
780 can be matched like an ordinary character. Examples:
781 "foo\nbar" =~ "\n" evaluates to 1
782 "foo\nbar" =~ "\\n" evaluates to 0
785 expr5 and expr6 *expr5* *expr6*
786 ---------------
787 expr6 + expr6 .. Number addition or |List| concatenation *expr-+*
788 expr6 - expr6 .. Number subtraction *expr--*
789 expr6 . expr6 .. String concatenation *expr-.*
791 For |Lists| only "+" is possible and then both expr6 must be a list. The
792 result is a new list with the two lists Concatenated.
794 expr7 * expr7 .. number multiplication *expr-star*
795 expr7 / expr7 .. number division *expr-/*
796 expr7 % expr7 .. number modulo *expr-%*
798 For all, except ".", Strings are converted to Numbers.
800 Note the difference between "+" and ".":
801 "123" + "456" = 579
802 "123" . "456" = "123456"
804 Since '.' has the same precedence as '+' and '-', you need to read: >
805 1 . 90 + 90.0
806 As: >
807 (1 . 90) + 90.0
808 That works, since the String "190" is automatically converted to the Number
809 190, which can be added to the Float 90.0. However: >
810 1 . 90 * 90.0
811 Should be read as: >
812 1 . (90 * 90.0)
813 Since '.' has lower precedence than '*'. This does NOT work, since this
814 attempts to concatenate a Float and a String.
816 When the righthand side of '/' is zero, the result is 0x7fffffff.
817 When the righthand side of '%' is zero, the result is 0.
819 None of these work for |Funcref|s.
821 . and % do not work for Float. *E804*
824 expr7 *expr7*
825 -----
826 ! expr7 logical NOT *expr-!*
827 - expr7 unary minus *expr-unary--*
828 + expr7 unary plus *expr-unary-+*
830 For '!' non-zero becomes zero, zero becomes one.
831 For '-' the sign of the number is changed.
832 For '+' the number is unchanged.
834 A String will be converted to a Number first.
836 These three can be repeated and mixed. Examples:
837 !-1 == 0
838 !!8 == 1
839 --9 == 9
842 expr8 *expr8*
843 -----
844 expr8[expr1] item of String or |List| *expr-[]* *E111*
846 If expr8 is a Number or String this results in a String that contains the
847 expr1'th single byte from expr8. expr8 is used as a String, expr1 as a
848 Number. Note that this doesn't recognize multi-byte encodings.
850 Index zero gives the first character. This is like it works in C. Careful:
851 text column numbers start with one! Example, to get the character under the
852 cursor: >
853 :let c = getline(".")[col(".") - 1]
855 If the length of the String is less than the index, the result is an empty
856 String. A negative index always results in an empty string (reason: backwards
857 compatibility). Use [-1:] to get the last byte.
859 If expr8 is a |List| then it results the item at index expr1. See |list-index|
860 for possible index values. If the index is out of range this results in an
861 error. Example: >
862 :let item = mylist[-1] " get last item
864 Generally, if a |List| index is equal to or higher than the length of the
865 |List|, or more negative than the length of the |List|, this results in an
866 error.
869 expr8[expr1a : expr1b] substring or sublist *expr-[:]*
871 If expr8 is a Number or String this results in the substring with the bytes
872 from expr1a to and including expr1b. expr8 is used as a String, expr1a and
873 expr1b are used as a Number. Note that this doesn't recognize multi-byte
874 encodings.
876 If expr1a is omitted zero is used. If expr1b is omitted the length of the
877 string minus one is used.
879 A negative number can be used to measure from the end of the string. -1 is
880 the last character, -2 the last but one, etc.
882 If an index goes out of range for the string characters are omitted. If
883 expr1b is smaller than expr1a the result is an empty string.
885 Examples: >
886 :let c = name[-1:] " last byte of a string
887 :let c = name[-2:-2] " last but one byte of a string
888 :let s = line(".")[4:] " from the fifth byte to the end
889 :let s = s[:-3] " remove last two bytes
891 If expr8 is a |List| this results in a new |List| with the items indicated by
892 the indexes expr1a and expr1b. This works like with a String, as explained
893 just above, except that indexes out of range cause an error. Examples: >
894 :let l = mylist[:3] " first four items
895 :let l = mylist[4:4] " List with one item
896 :let l = mylist[:] " shallow copy of a List
898 Using expr8[expr1] or expr8[expr1a : expr1b] on a |Funcref| results in an
899 error.
902 expr8.name entry in a |Dictionary| *expr-entry*
904 If expr8 is a |Dictionary| and it is followed by a dot, then the following
905 name will be used as a key in the |Dictionary|. This is just like:
906 expr8[name].
908 The name must consist of alphanumeric characters, just like a variable name,
909 but it may start with a number. Curly braces cannot be used.
911 There must not be white space before or after the dot.
913 Examples: >
914 :let dict = {"one": 1, 2: "two"}
915 :echo dict.one
916 :echo dict .2
918 Note that the dot is also used for String concatenation. To avoid confusion
919 always put spaces around the dot for String concatenation.
922 expr8(expr1, ...) |Funcref| function call
924 When expr8 is a |Funcref| type variable, invoke the function it refers to.
928 *expr9*
929 number
930 ------
931 number number constant *expr-number*
933 Decimal, Hexadecimal (starting with 0x or 0X), or Octal (starting with 0).
935 *floating-point-format*
936 Floating point numbers can be written in two forms:
938 [-+]{N}.{M}
939 [-+]{N}.{M}e[-+]{exp}
941 {N} and {M} are numbers. Both {N} and {M} must be present and can only
942 contain digits.
943 [-+] means there is an optional plus or minus sign.
944 {exp} is the exponent, power of 10.
945 Only a decimal point is accepted, not a comma. No matter what the current
946 locale is.
947 {only when compiled with the |+float| feature}
949 Examples:
950 123.456
951 +0.0001
952 55.0
953 -0.123
954 1.234e03
955 1.0E-6
956 -3.1416e+88
958 These are INVALID:
959 3. empty {M}
960 1e40 missing .{M}
962 The precision and range of floating points numbers depends on the library Vim
963 was compiled with. There is no way to change this at runtime.
965 Rationale:
966 Before floating point was introduced, the text "123.456" was interpreted as
967 the two numbers "123" and "456", both converted to a string and concatenated,
968 resulting in the string "123456". Since this was considered pointless, and we
969 could not find it actually being used in Vim scripts, this backwards
970 incompatibility was accepted in favor of being able to use the normal notation
971 for floating point numbers.
974 string *expr-string* *E114*
975 ------
976 "string" string constant *expr-quote*
978 Note that double quotes are used.
980 A string constant accepts these special characters:
981 \... three-digit octal number (e.g., "\316")
982 \.. two-digit octal number (must be followed by non-digit)
983 \. one-digit octal number (must be followed by non-digit)
984 \x.. byte specified with two hex numbers (e.g., "\x1f")
985 \x. byte specified with one hex number (must be followed by non-hex char)
986 \X.. same as \x..
987 \X. same as \x.
988 \u.... character specified with up to 4 hex numbers, stored according to the
989 current value of 'encoding' (e.g., "\u02a4")
990 \U.... same as \u....
991 \b backspace <BS>
992 \e escape <Esc>
993 \f formfeed <FF>
994 \n newline <NL>
995 \r return <CR>
996 \t tab <Tab>
997 \\ backslash
998 \" double quote
999 \<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W.
1001 Note that "\xff" is stored as the byte 255, which may be invalid in some
1002 encodings. Use "\u00ff" to store character 255 according to the current value
1003 of 'encoding'.
1005 Note that "\000" and "\x00" force the end of the string.
1008 literal-string *literal-string* *E115*
1009 ---------------
1010 'string' string constant *expr-'*
1012 Note that single quotes are used.
1014 This string is taken as it is. No backslashes are removed or have a special
1015 meaning. The only exception is that two quotes stand for one quote.
1017 Single quoted strings are useful for patterns, so that backslashes do not need
1018 to be doubled. These two commands are equivalent: >
1019 if a =~ "\\s*"
1020 if a =~ '\s*'
1023 option *expr-option* *E112* *E113*
1024 ------
1025 &option option value, local value if possible
1026 &g:option global option value
1027 &l:option local option value
1029 Examples: >
1030 echo "tabstop is " . &tabstop
1031 if &insertmode
1033 Any option name can be used here. See |options|. When using the local value
1034 and there is no buffer-local or window-local value, the global value is used
1035 anyway.
1038 register *expr-register* *@r*
1039 --------
1040 @r contents of register 'r'
1042 The result is the contents of the named register, as a single string.
1043 Newlines are inserted where required. To get the contents of the unnamed
1044 register use @" or @@. See |registers| for an explanation of the available
1045 registers.
1047 When using the '=' register you get the expression itself, not what it
1048 evaluates to. Use |eval()| to evaluate it.
1051 nesting *expr-nesting* *E110*
1052 -------
1053 (expr1) nested expression
1056 environment variable *expr-env*
1057 --------------------
1058 $VAR environment variable
1060 The String value of any environment variable. When it is not defined, the
1061 result is an empty string.
1062 *expr-env-expand*
1063 Note that there is a difference between using $VAR directly and using
1064 expand("$VAR"). Using it directly will only expand environment variables that
1065 are known inside the current Vim session. Using expand() will first try using
1066 the environment variables known inside the current Vim session. If that
1067 fails, a shell will be used to expand the variable. This can be slow, but it
1068 does expand all variables that the shell knows about. Example: >
1069 :echo $version
1070 :echo expand("$version")
1071 The first one probably doesn't echo anything, the second echoes the $version
1072 variable (if your shell supports it).
1075 internal variable *expr-variable*
1076 -----------------
1077 variable internal variable
1078 See below |internal-variables|.
1081 function call *expr-function* *E116* *E118* *E119* *E120*
1082 -------------
1083 function(expr1, ...) function call
1084 See below |functions|.
1087 ==============================================================================
1088 3. Internal variable *internal-variables* *E121*
1089 *E461*
1090 An internal variable name can be made up of letters, digits and '_'. But it
1091 cannot start with a digit. It's also possible to use curly braces, see
1092 |curly-braces-names|.
1094 An internal variable is created with the ":let" command |:let|.
1095 An internal variable is explicitly destroyed with the ":unlet" command
1096 |:unlet|.
1097 Using a name that is not an internal variable or refers to a variable that has
1098 been destroyed results in an error.
1100 There are several name spaces for variables. Which one is to be used is
1101 specified by what is prepended:
1103 (nothing) In a function: local to a function; otherwise: global
1104 |buffer-variable| b: Local to the current buffer.
1105 |window-variable| w: Local to the current window.
1106 |tabpage-variable| t: Local to the current tab page.
1107 |global-variable| g: Global.
1108 |local-variable| l: Local to a function.
1109 |script-variable| s: Local to a |:source|'ed Vim script.
1110 |function-argument| a: Function argument (only inside a function).
1111 |vim-variable| v: Global, predefined by Vim.
1113 The scope name by itself can be used as a |Dictionary|. For example, to
1114 delete all script-local variables: >
1115 :for k in keys(s:)
1116 : unlet s:[k]
1117 :endfor
1118 <
1119 *buffer-variable* *b:var*
1120 A variable name that is preceded with "b:" is local to the current buffer.
1121 Thus you can have several "b:foo" variables, one for each buffer.
1122 This kind of variable is deleted when the buffer is wiped out or deleted with
1123 |:bdelete|.
1125 One local buffer variable is predefined:
1126 *b:changedtick-variable* *changetick*
1127 b:changedtick The total number of changes to the current buffer. It is
1128 incremented for each change. An undo command is also a change
1129 in this case. This can be used to perform an action only when
1130 the buffer has changed. Example: >
1131 :if my_changedtick != b:changedtick
1132 : let my_changedtick = b:changedtick
1133 : call My_Update()
1134 :endif
1135 <
1136 *window-variable* *w:var*
1137 A variable name that is preceded with "w:" is local to the current window. It
1138 is deleted when the window is closed.
1140 *tabpage-variable* *t:var*
1141 A variable name that is preceded with "t:" is local to the current tab page,
1142 It is deleted when the tab page is closed. {not available when compiled
1143 without the +windows feature}
1145 *global-variable* *g:var*
1146 Inside functions global variables are accessed with "g:". Omitting this will
1147 access a variable local to a function. But "g:" can also be used in any other
1148 place if you like.
1150 *local-variable* *l:var*
1151 Inside functions local variables are accessed without prepending anything.
1152 But you can also prepend "l:" if you like. However, without prepending "l:"
1153 you may run into reserved variable names. For example "count". By itself it
1154 refers to "v:count". Using "l:count" you can have a local variable with the
1155 same name.
1157 *script-variable* *s:var*
1158 In a Vim script variables starting with "s:" can be used. They cannot be
1159 accessed from outside of the scripts, thus are local to the script.
1161 They can be used in:
1162 - commands executed while the script is sourced
1163 - functions defined in the script
1164 - autocommands defined in the script
1165 - functions and autocommands defined in functions and autocommands which were
1166 defined in the script (recursively)
1167 - user defined commands defined in the script
1168 Thus not in:
1169 - other scripts sourced from this one
1170 - mappings
1171 - etc.
1173 Script variables can be used to avoid conflicts with global variable names.
1174 Take this example: >
1176 let s:counter = 0
1177 function MyCounter()
1178 let s:counter = s:counter + 1
1179 echo s:counter
1180 endfunction
1181 command Tick call MyCounter()
1183 You can now invoke "Tick" from any script, and the "s:counter" variable in
1184 that script will not be changed, only the "s:counter" in the script where
1185 "Tick" was defined is used.
1187 Another example that does the same: >
1189 let s:counter = 0
1190 command Tick let s:counter = s:counter + 1 | echo s:counter
1192 When calling a function and invoking a user-defined command, the context for
1193 script variables is set to the script where the function or command was
1194 defined.
1196 The script variables are also available when a function is defined inside a
1197 function that is defined in a script. Example: >
1199 let s:counter = 0
1200 function StartCounting(incr)
1201 if a:incr
1202 function MyCounter()
1203 let s:counter = s:counter + 1
1204 endfunction
1205 else
1206 function MyCounter()
1207 let s:counter = s:counter - 1
1208 endfunction
1209 endif
1210 endfunction
1212 This defines the MyCounter() function either for counting up or counting down
1213 when calling StartCounting(). It doesn't matter from where StartCounting() is
1214 called, the s:counter variable will be accessible in MyCounter().
1216 When the same script is sourced again it will use the same script variables.
1217 They will remain valid as long as Vim is running. This can be used to
1218 maintain a counter: >
1220 if !exists("s:counter")
1221 let s:counter = 1
1222 echo "script executed for the first time"
1223 else
1224 let s:counter = s:counter + 1
1225 echo "script executed " . s:counter . " times now"
1226 endif
1228 Note that this means that filetype plugins don't get a different set of script
1229 variables for each buffer. Use local buffer variables instead |b:var|.
1232 Predefined Vim variables: *vim-variable* *v:var*
1234 *v:beval_col* *beval_col-variable*
1235 v:beval_col The number of the column, over which the mouse pointer is.
1236 This is the byte index in the |v:beval_lnum| line.
1237 Only valid while evaluating the 'balloonexpr' option.
1239 *v:beval_bufnr* *beval_bufnr-variable*
1240 v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only
1241 valid while evaluating the 'balloonexpr' option.
1243 *v:beval_lnum* *beval_lnum-variable*
1244 v:beval_lnum The number of the line, over which the mouse pointer is. Only
1245 valid while evaluating the 'balloonexpr' option.
1247 *v:beval_text* *beval_text-variable*
1248 v:beval_text The text under or after the mouse pointer. Usually a word as
1249 it is useful for debugging a C program. 'iskeyword' applies,
1250 but a dot and "->" before the position is included. When on a
1251 ']' the text before it is used, including the matching '[' and
1252 word before it. When on a Visual area within one line the
1253 highlighted text is used.
1254 Only valid while evaluating the 'balloonexpr' option.
1256 *v:beval_winnr* *beval_winnr-variable*
1257 v:beval_winnr The number of the window, over which the mouse pointer is. Only
1258 valid while evaluating the 'balloonexpr' option.
1260 *v:char* *char-variable*
1261 v:char Argument for evaluating 'formatexpr'.
1263 *v:charconvert_from* *charconvert_from-variable*
1264 v:charconvert_from
1265 The name of the character encoding of a file to be converted.
1266 Only valid while evaluating the 'charconvert' option.
1268 *v:charconvert_to* *charconvert_to-variable*
1269 v:charconvert_to
1270 The name of the character encoding of a file after conversion.
1271 Only valid while evaluating the 'charconvert' option.
1273 *v:cmdarg* *cmdarg-variable*
1274 v:cmdarg This variable is used for two purposes:
1275 1. The extra arguments given to a file read/write command.
1276 Currently these are "++enc=" and "++ff=". This variable is
1277 set before an autocommand event for a file read/write
1278 command is triggered. There is a leading space to make it
1279 possible to append this variable directly after the
1280 read/write command. Note: The "+cmd" argument isn't
1281 included here, because it will be executed anyway.
1282 2. When printing a PostScript file with ":hardcopy" this is
1283 the argument for the ":hardcopy" command. This can be used
1284 in 'printexpr'.
1286 *v:cmdbang* *cmdbang-variable*
1287 v:cmdbang Set like v:cmdarg for a file read/write command. When a "!"
1288 was used the value is 1, otherwise it is 0. Note that this
1289 can only be used in autocommands. For user commands |<bang>|
1290 can be used.
1292 *v:count* *count-variable*
1293 v:count The count given for the last Normal mode command. Can be used
1294 to get the count before a mapping. Read-only. Example: >
1295 :map _x :<C-U>echo "the count is " . v:count<CR>
1296 < Note: The <C-U> is required to remove the line range that you
1297 get when typing ':' after a count.
1298 Also used for evaluating the 'formatexpr' option.
1299 "count" also works, for backwards compatibility.
1301 *v:count1* *count1-variable*
1302 v:count1 Just like "v:count", but defaults to one when no count is
1303 used.
1305 *v:ctype* *ctype-variable*
1306 v:ctype The current locale setting for characters of the runtime
1307 environment. This allows Vim scripts to be aware of the
1308 current locale encoding. Technical: it's the value of
1309 LC_CTYPE. When not using a locale the value is "C".
1310 This variable can not be set directly, use the |:language|
1311 command.
1312 See |multi-lang|.
1314 *v:dying* *dying-variable*
1315 v:dying Normally zero. When a deadly signal is caught it's set to
1316 one. When multiple signals are caught the number increases.
1317 Can be used in an autocommand to check if Vim didn't
1318 terminate normally. {only works on Unix}
1319 Example: >
1320 :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
1321 <
1322 *v:errmsg* *errmsg-variable*
1323 v:errmsg Last given error message. It's allowed to set this variable.
1324 Example: >
1325 :let v:errmsg = ""
1326 :silent! next
1327 :if v:errmsg != ""
1328 : ... handle error
1329 < "errmsg" also works, for backwards compatibility.
1331 *v:exception* *exception-variable*
1332 v:exception The value of the exception most recently caught and not
1333 finished. See also |v:throwpoint| and |throw-variables|.
1334 Example: >
1335 :try
1336 : throw "oops"
1337 :catch /.*/
1338 : echo "caught" v:exception
1339 :endtry
1340 < Output: "caught oops".
1342 *v:fcs_reason* *fcs_reason-variable*
1343 v:fcs_reason The reason why the |FileChangedShell| event was triggered.
1344 Can be used in an autocommand to decide what to do and/or what
1345 to set v:fcs_choice to. Possible values:
1346 deleted file no longer exists
1347 conflict file contents, mode or timestamp was
1348 changed and buffer is modified
1349 changed file contents has changed
1350 mode mode of file changed
1351 time only file timestamp changed
1353 *v:fcs_choice* *fcs_choice-variable*
1354 v:fcs_choice What should happen after a |FileChangedShell| event was
1355 triggered. Can be used in an autocommand to tell Vim what to
1356 do with the affected buffer:
1357 reload Reload the buffer (does not work if
1358 the file was deleted).
1359 ask Ask the user what to do, as if there
1360 was no autocommand. Except that when
1361 only the timestamp changed nothing
1362 will happen.
1363 <empty> Nothing, the autocommand should do
1364 everything that needs to be done.
1365 The default is empty. If another (invalid) value is used then
1366 Vim behaves like it is empty, there is no warning message.
1368 *v:fname_in* *fname_in-variable*
1369 v:fname_in The name of the input file. Valid while evaluating:
1370 option used for ~
1371 'charconvert' file to be converted
1372 'diffexpr' original file
1373 'patchexpr' original file
1374 'printexpr' file to be printed
1375 And set to the swap file name for |SwapExists|.
1377 *v:fname_out* *fname_out-variable*
1378 v:fname_out The name of the output file. Only valid while
1379 evaluating:
1380 option used for ~
1381 'charconvert' resulting converted file (*)
1382 'diffexpr' output of diff
1383 'patchexpr' resulting patched file
1384 (*) When doing conversion for a write command (e.g., ":w
1385 file") it will be equal to v:fname_in. When doing conversion
1386 for a read command (e.g., ":e file") it will be a temporary
1387 file and different from v:fname_in.
1389 *v:fname_new* *fname_new-variable*
1390 v:fname_new The name of the new version of the file. Only valid while
1391 evaluating 'diffexpr'.
1393 *v:fname_diff* *fname_diff-variable*
1394 v:fname_diff The name of the diff (patch) file. Only valid while
1395 evaluating 'patchexpr'.
1397 *v:folddashes* *folddashes-variable*
1398 v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed
1399 fold.
1400 Read-only in the |sandbox|. |fold-foldtext|
1402 *v:foldlevel* *foldlevel-variable*
1403 v:foldlevel Used for 'foldtext': foldlevel of closed fold.
1404 Read-only in the |sandbox|. |fold-foldtext|
1406 *v:foldend* *foldend-variable*
1407 v:foldend Used for 'foldtext': last line of closed fold.
1408 Read-only in the |sandbox|. |fold-foldtext|
1410 *v:foldstart* *foldstart-variable*
1411 v:foldstart Used for 'foldtext': first line of closed fold.
1412 Read-only in the |sandbox|. |fold-foldtext|
1414 *v:insertmode* *insertmode-variable*
1415 v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand
1416 events. Values:
1417 i Insert mode
1418 r Replace mode
1419 v Virtual Replace mode
1421 *v:key* *key-variable*
1422 v:key Key of the current item of a |Dictionary|. Only valid while
1423 evaluating the expression used with |map()| and |filter()|.
1424 Read-only.
1426 *v:lang* *lang-variable*
1427 v:lang The current locale setting for messages of the runtime
1428 environment. This allows Vim scripts to be aware of the
1429 current language. Technical: it's the value of LC_MESSAGES.
1430 The value is system dependent.
1431 This variable can not be set directly, use the |:language|
1432 command.
1433 It can be different from |v:ctype| when messages are desired
1434 in a different language than what is used for character
1435 encoding. See |multi-lang|.
1437 *v:lc_time* *lc_time-variable*
1438 v:lc_time The current locale setting for time messages of the runtime
1439 environment. This allows Vim scripts to be aware of the
1440 current language. Technical: it's the value of LC_TIME.
1441 This variable can not be set directly, use the |:language|
1442 command. See |multi-lang|.
1444 *v:lnum* *lnum-variable*
1445 v:lnum Line number for the 'foldexpr' |fold-expr| and 'indentexpr'
1446 expressions, tab page number for 'guitablabel' and
1447 'guitabtooltip'. Only valid while one of these expressions is
1448 being evaluated. Read-only when in the |sandbox|.
1450 *v:mouse_win* *mouse_win-variable*
1451 v:mouse_win Window number for a mouse click obtained with |getchar()|.
1452 First window has number 1, like with |winnr()|. The value is
1453 zero when there was no mouse button click.
1455 *v:mouse_lnum* *mouse_lnum-variable*
1456 v:mouse_lnum Line number for a mouse click obtained with |getchar()|.
1457 This is the text line number, not the screen line number. The
1458 value is zero when there was no mouse button click.
1460 *v:mouse_col* *mouse_col-variable*
1461 v:mouse_col Column number for a mouse click obtained with |getchar()|.
1462 This is the screen column number, like with |virtcol()|. The
1463 value is zero when there was no mouse button click.
1465 *v:operator* *operator-variable*
1466 v:operator The last operator given in Normal mode. This is a single
1467 character except for commands starting with <g> or <z>,
1468 in which case it is two characters. Best used alongside
1469 |v:prevcount| and |v:register|. Useful if you want to cancel
1470 Operator-pending mode and then use the operator, e.g.: >
1471 :omap O <Esc>:call MyMotion(v:operator)<CR>
1472 < The value remains set until another operator is entered, thus
1473 don't expect it to be empty.
1474 v:operator is not set for |:delete|, |:yank| or other Ex
1475 commands.
1476 Read-only.
1478 *v:prevcount* *prevcount-variable*
1479 v:prevcount The count given for the last but one Normal mode command.
1480 This is the v:count value of the previous command. Useful if
1481 you want to cancel Visual or Operator-pending mode and then
1482 use the count, e.g.: >
1483 :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
1484 < Read-only.
1486 *v:profiling* *profiling-variable*
1487 v:profiling Normally zero. Set to one after using ":profile start".
1488 See |profiling|.
1490 *v:progname* *progname-variable*
1491 v:progname Contains the name (with path removed) with which Vim was
1492 invoked. Allows you to do special initialisations for "view",
1493 "evim" etc., or any other name you might symlink to Vim.
1494 Read-only.
1496 *v:register* *register-variable*
1497 v:register The name of the register supplied to the last normal mode
1498 command. Empty if none were supplied. |getreg()| |setreg()|
1500 *v:scrollstart* *scrollstart-variable*
1501 v:scrollstart String describing the script or function that caused the
1502 screen to scroll up. It's only set when it is empty, thus the
1503 first reason is remembered. It is set to "Unknown" for a
1504 typed command.
1505 This can be used to find out why your script causes the
1506 hit-enter prompt.
1508 *v:servername* *servername-variable*
1509 v:servername The resulting registered |x11-clientserver| name if any.
1510 Read-only.
1512 *v:shell_error* *shell_error-variable*
1513 v:shell_error Result of the last shell command. When non-zero, the last
1514 shell command had an error. When zero, there was no problem.
1515 This only works when the shell returns the error code to Vim.
1516 The value -1 is often used when the command could not be
1517 executed. Read-only.
1518 Example: >
1519 :!mv foo bar
1520 :if v:shell_error
1521 : echo 'could not rename "foo" to "bar"!'
1522 :endif
1523 < "shell_error" also works, for backwards compatibility.
1525 *v:statusmsg* *statusmsg-variable*
1526 v:statusmsg Last given status message. It's allowed to set this variable.
1528 *v:swapname* *swapname-variable*
1529 v:swapname Only valid when executing |SwapExists| autocommands: Name of
1530 the swap file found. Read-only.
1532 *v:swapchoice* *swapchoice-variable*
1533 v:swapchoice |SwapExists| autocommands can set this to the selected choice
1534 for handling an existing swap file:
1535 'o' Open read-only
1536 'e' Edit anyway
1537 'r' Recover
1538 'd' Delete swapfile
1539 'q' Quit
1540 'a' Abort
1541 The value should be a single-character string. An empty value
1542 results in the user being asked, as would happen when there is
1543 no SwapExists autocommand. The default is empty.
1545 *v:swapcommand* *swapcommand-variable*
1546 v:swapcommand Normal mode command to be executed after a file has been
1547 opened. Can be used for a |SwapExists| autocommand to have
1548 another Vim open the file and jump to the right place. For
1549 example, when jumping to a tag the value is ":tag tagname\r".
1550 For ":edit +cmd file" the value is ":cmd\r".
1552 *v:termresponse* *termresponse-variable*
1553 v:termresponse The escape sequence returned by the terminal for the |t_RV|
1554 termcap entry. It is set when Vim receives an escape sequence
1555 that starts with ESC [ or CSI and ends in a 'c', with only
1556 digits, ';' and '.' in between.
1557 When this option is set, the TermResponse autocommand event is
1558 fired, so that you can react to the response from the
1559 terminal.
1560 The response from a new xterm is: "<Esc>[ Pp ; Pv ; Pc c". Pp
1561 is the terminal type: 0 for vt100 and 1 for vt220. Pv is the
1562 patch level (since this was introduced in patch 95, it's
1563 always 95 or bigger). Pc is always zero.
1564 {only when compiled with |+termresponse| feature}
1566 *v:this_session* *this_session-variable*
1567 v:this_session Full filename of the last loaded or saved session file. See
1568 |:mksession|. It is allowed to set this variable. When no
1569 session file has been saved, this variable is empty.
1570 "this_session" also works, for backwards compatibility.
1572 *v:throwpoint* *throwpoint-variable*
1573 v:throwpoint The point where the exception most recently caught and not
1574 finished was thrown. Not set when commands are typed. See
1575 also |v:exception| and |throw-variables|.
1576 Example: >
1577 :try
1578 : throw "oops"
1579 :catch /.*/
1580 : echo "Exception from" v:throwpoint
1581 :endtry
1582 < Output: "Exception from test.vim, line 2"
1584 *v:val* *val-variable*
1585 v:val Value of the current item of a |List| or |Dictionary|. Only
1586 valid while evaluating the expression used with |map()| and
1587 |filter()|. Read-only.
1589 *v:version* *version-variable*
1590 v:version Version number of Vim: Major version number times 100 plus
1591 minor version number. Version 5.0 is 500. Version 5.1 (5.01)
1592 is 501. Read-only. "version" also works, for backwards
1593 compatibility.
1594 Use |has()| to check if a certain patch was included, e.g.: >
1595 if has("patch123")
1596 < Note that patch numbers are specific to the version, thus both
1597 version 5.0 and 5.1 may have a patch 123, but these are
1598 completely different.
1600 *v:warningmsg* *warningmsg-variable*
1601 v:warningmsg Last given warning message. It's allowed to set this variable.
1603 ==============================================================================
1604 4. Builtin Functions *functions*
1606 See |function-list| for a list grouped by what the function is used for.
1608 (Use CTRL-] on the function name to jump to the full explanation.)
1610 USAGE RESULT DESCRIPTION ~
1612 add( {list}, {item}) List append {item} to |List| {list}
1613 append( {lnum}, {string}) Number append {string} below line {lnum}
1614 append( {lnum}, {list}) Number append lines {list} below line {lnum}
1615 argc() Number number of files in the argument list
1616 argidx() Number current index in the argument list
1617 argv( {nr}) String {nr} entry of the argument list
1618 argv( ) List the argument list
1619 browse( {save}, {title}, {initdir}, {default})
1620 String put up a file requester
1621 browsedir( {title}, {initdir}) String put up a directory requester
1622 bufexists( {expr}) Number TRUE if buffer {expr} exists
1623 buflisted( {expr}) Number TRUE if buffer {expr} is listed
1624 bufloaded( {expr}) Number TRUE if buffer {expr} is loaded
1625 bufname( {expr}) String Name of the buffer {expr}
1626 bufnr( {expr}) Number Number of the buffer {expr}
1627 bufwinnr( {expr}) Number window number of buffer {expr}
1628 byte2line( {byte}) Number line number at byte count {byte}
1629 byteidx( {expr}, {nr}) Number byte index of {nr}'th char in {expr}
1630 call( {func}, {arglist} [, {dict}])
1631 any call {func} with arguments {arglist}
1632 ceil( {expr}) Float round {expr} up
1633 changenr() Number current change number
1634 char2nr( {expr}) Number ASCII value of first char in {expr}
1635 cindent( {lnum}) Number C indent for line {lnum}
1636 clearmatches() None clear all matches
1637 col( {expr}) Number column nr of cursor or mark
1638 complete({startcol}, {matches}) String set Insert mode completion
1639 complete_add( {expr}) Number add completion match
1640 complete_check() Number check for key typed during completion
1641 confirm( {msg} [, {choices} [, {default} [, {type}]]])
1642 Number number of choice picked by user
1643 copy( {expr}) any make a shallow copy of {expr}
1644 count( {list}, {expr} [, {start} [, {ic}]])
1645 Number count how many {expr} are in {list}
1646 cscope_connection( [{num} , {dbpath} [, {prepend}]])
1647 Number checks existence of cscope connection
1648 cursor( {lnum}, {col} [, {coladd}])
1649 Number move cursor to {lnum}, {col}, {coladd}
1650 cursor( {list}) Number move cursor to position in {list}
1651 deepcopy( {expr}) any make a full copy of {expr}
1652 delete( {fname}) Number delete file {fname}
1653 did_filetype() Number TRUE if FileType autocommand event used
1654 diff_filler( {lnum}) Number diff filler lines about {lnum}
1655 diff_hlID( {lnum}, {col}) Number diff highlighting at {lnum}/{col}
1656 empty( {expr}) Number TRUE if {expr} is empty
1657 escape( {string}, {chars}) String escape {chars} in {string} with '\'
1658 eval( {string}) any evaluate {string} into its value
1659 eventhandler( ) Number TRUE if inside an event handler
1660 executable( {expr}) Number 1 if executable {expr} exists
1661 exists( {expr}) Number TRUE if {expr} exists
1662 extend({expr1}, {expr2} [, {expr3}])
1663 List/Dict insert items of {expr2} into {expr1}
1664 expand( {expr}) String expand special keywords in {expr}
1665 feedkeys( {string} [, {mode}]) Number add key sequence to typeahead buffer
1666 filereadable( {file}) Number TRUE if {file} is a readable file
1667 filewritable( {file}) Number TRUE if {file} is a writable file
1668 filter( {expr}, {string}) List/Dict remove items from {expr} where
1669 {string} is 0
1670 finddir( {name}[, {path}[, {count}]])
1671 String find directory {name} in {path}
1672 findfile( {name}[, {path}[, {count}]])
1673 String find file {name} in {path}
1674 float2nr( {expr}) Number convert Float {expr} to a Number
1675 floor( {expr}) Float round {expr} down
1676 fnameescape( {fname}) String escape special characters in {fname}
1677 fnamemodify( {fname}, {mods}) String modify file name
1678 foldclosed( {lnum}) Number first line of fold at {lnum} if closed
1679 foldclosedend( {lnum}) Number last line of fold at {lnum} if closed
1680 foldlevel( {lnum}) Number fold level at {lnum}
1681 foldtext( ) String line displayed for closed fold
1682 foldtextresult( {lnum}) String text for closed fold at {lnum}
1683 foreground( ) Number bring the Vim window to the foreground
1684 function( {name}) Funcref reference to function {name}
1685 garbagecollect( [at_exit]) none free memory, breaking cyclic references
1686 get( {list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
1687 get( {dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
1688 getbufline( {expr}, {lnum} [, {end}])
1689 List lines {lnum} to {end} of buffer {expr}
1690 getbufvar( {expr}, {varname}) any variable {varname} in buffer {expr}
1691 getchar( [expr]) Number get one character from the user
1692 getcharmod( ) Number modifiers for the last typed character
1693 getcmdline() String return the current command-line
1694 getcmdpos() Number return cursor position in command-line
1695 getcmdtype() String return the current command-line type
1696 getcwd() String the current working directory
1697 getfperm( {fname}) String file permissions of file {fname}
1698 getfsize( {fname}) Number size in bytes of file {fname}
1699 getfontname( [{name}]) String name of font being used
1700 getftime( {fname}) Number last modification time of file
1701 getftype( {fname}) String description of type of file {fname}
1702 getline( {lnum}) String line {lnum} of current buffer
1703 getline( {lnum}, {end}) List lines {lnum} to {end} of current buffer
1704 getloclist({nr}) List list of location list items
1705 getmatches() List list of current matches
1706 getpid() Number process ID of Vim
1707 getpos( {expr}) List position of cursor, mark, etc.
1708 getqflist() List list of quickfix items
1709 getreg( [{regname} [, 1]]) String contents of register
1710 getregtype( [{regname}]) String type of register
1711 gettabwinvar( {tabnr}, {winnr}, {name})
1712 any {name} in {winnr} in tab page {tabnr}
1713 getwinposx() Number X coord in pixels of GUI Vim window
1714 getwinposy() Number Y coord in pixels of GUI Vim window
1715 getwinvar( {nr}, {varname}) any variable {varname} in window {nr}
1716 glob( {expr}) String expand file wildcards in {expr}
1717 globpath( {path}, {expr}) String do glob({expr}) for all dirs in {path}
1718 has( {feature}) Number TRUE if feature {feature} supported
1719 has_key( {dict}, {key}) Number TRUE if {dict} has entry {key}
1720 haslocaldir() Number TRUE if current window executed |:lcd|
1721 hasmapto( {what} [, {mode} [, {abbr}]])
1722 Number TRUE if mapping to {what} exists
1723 histadd( {history},{item}) String add an item to a history
1724 histdel( {history} [, {item}]) String remove an item from a history
1725 histget( {history} [, {index}]) String get the item {index} from a history
1726 histnr( {history}) Number highest index of a history
1727 hlexists( {name}) Number TRUE if highlight group {name} exists
1728 hlID( {name}) Number syntax ID of highlight group {name}
1729 hostname() String name of the machine Vim is running on
1730 iconv( {expr}, {from}, {to}) String convert encoding of {expr}
1731 indent( {lnum}) Number indent of line {lnum}
1732 index( {list}, {expr} [, {start} [, {ic}]])
1733 Number index in {list} where {expr} appears
1734 input( {prompt} [, {text} [, {completion}]])
1735 String get input from the user
1736 inputdialog( {p} [, {t} [, {c}]]) String like input() but in a GUI dialog
1737 inputlist( {textlist}) Number let the user pick from a choice list
1738 inputrestore() Number restore typeahead
1739 inputsave() Number save and clear typeahead
1740 inputsecret( {prompt} [, {text}]) String like input() but hiding the text
1741 insert( {list}, {item} [, {idx}]) List insert {item} in {list} [before {idx}]
1742 isdirectory( {directory}) Number TRUE if {directory} is a directory
1743 islocked( {expr}) Number TRUE if {expr} is locked
1744 items( {dict}) List key-value pairs in {dict}
1745 join( {list} [, {sep}]) String join {list} items into one String
1746 keys( {dict}) List keys in {dict}
1747 len( {expr}) Number the length of {expr}
1748 libcall( {lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
1749 libcallnr( {lib}, {func}, {arg}) Number idem, but return a Number
1750 line( {expr}) Number line nr of cursor, last line or mark
1751 line2byte( {lnum}) Number byte count of line {lnum}
1752 lispindent( {lnum}) Number Lisp indent for line {lnum}
1753 localtime() Number current time
1754 log10( {expr}) Float logarithm of Float {expr} to base 10
1755 map( {expr}, {string}) List/Dict change each item in {expr} to {expr}
1756 maparg( {name}[, {mode} [, {abbr}]])
1757 String rhs of mapping {name} in mode {mode}
1758 mapcheck( {name}[, {mode} [, {abbr}]])
1759 String check for mappings matching {name}
1760 match( {expr}, {pat}[, {start}[, {count}]])
1761 Number position where {pat} matches in {expr}
1762 matchadd( {group}, {pattern}[, {priority}[, {id}]])
1763 Number highlight {pattern} with {group}
1764 matcharg( {nr}) List arguments of |:match|
1765 matchdelete( {id}) Number delete match identified by {id}
1766 matchend( {expr}, {pat}[, {start}[, {count}]])
1767 Number position where {pat} ends in {expr}
1768 matchlist( {expr}, {pat}[, {start}[, {count}]])
1769 List match and submatches of {pat} in {expr}
1770 matchstr( {expr}, {pat}[, {start}[, {count}]])
1771 String {count}'th match of {pat} in {expr}
1772 max({list}) Number maximum value of items in {list}
1773 min({list}) Number minimum value of items in {list}
1774 mkdir({name} [, {path} [, {prot}]])
1775 Number create directory {name}
1776 mode() String current editing mode
1777 nextnonblank( {lnum}) Number line nr of non-blank line >= {lnum}
1778 nr2char( {expr}) String single char with ASCII value {expr}
1779 pathshorten( {expr}) String shorten directory names in a path
1780 pow( {x}, {y}) Float {x} to the power of {y}
1781 prevnonblank( {lnum}) Number line nr of non-blank line <= {lnum}
1782 printf( {fmt}, {expr1}...) String format text
1783 pumvisible() Number whether popup menu is visible
1784 range( {expr} [, {max} [, {stride}]])
1785 List items from {expr} to {max}
1786 readfile({fname} [, {binary} [, {max}]])
1787 List get list of lines from file {fname}
1788 reltime( [{start} [, {end}]]) List get time value
1789 reltimestr( {time}) String turn time value into a String
1790 remote_expr( {server}, {string} [, {idvar}])
1791 String send expression
1792 remote_foreground( {server}) Number bring Vim server to the foreground
1793 remote_peek( {serverid} [, {retvar}])
1794 Number check for reply string
1795 remote_read( {serverid}) String read reply string
1796 remote_send( {server}, {string} [, {idvar}])
1797 String send key sequence
1798 remove( {list}, {idx} [, {end}]) any remove items {idx}-{end} from {list}
1799 remove( {dict}, {key}) any remove entry {key} from {dict}
1800 rename( {from}, {to}) Number rename (move) file from {from} to {to}
1801 repeat( {expr}, {count}) String repeat {expr} {count} times
1802 resolve( {filename}) String get filename a shortcut points to
1803 reverse( {list}) List reverse {list} in-place
1804 round( {expr}) Float round off {expr}
1805 search( {pattern} [, {flags} [, {stopline} [, {timeout}]]])
1806 Number search for {pattern}
1807 searchdecl({name} [, {global} [, {thisblock}]])
1808 Number search for variable declaration
1809 searchpair( {start}, {middle}, {end} [, {flags} [, {skip} [...]]])
1810 Number search for other end of start/end pair
1811 searchpairpos( {start}, {middle}, {end} [, {flags} [, {skip} [...]]])
1812 List search for other end of start/end pair
1813 searchpos( {pattern} [, {flags} [, {stopline} [, {timeout}]]])
1814 List search for {pattern}
1815 server2client( {clientid}, {string})
1816 Number send reply string
1817 serverlist() String get a list of available servers
1818 setbufvar( {expr}, {varname}, {val}) set {varname} in buffer {expr} to {val}
1819 setcmdpos( {pos}) Number set cursor position in command-line
1820 setline( {lnum}, {line}) Number set line {lnum} to {line}
1821 setloclist( {nr}, {list}[, {action}])
1822 Number modify location list using {list}
1823 setmatches( {list}) Number restore a list of matches
1824 setpos( {expr}, {list}) none set the {expr} position to {list}
1825 setqflist( {list}[, {action}]) Number modify quickfix list using {list}
1826 setreg( {n}, {v}[, {opt}]) Number set register to value and type
1827 settabwinvar( {tabnr}, {winnr}, {varname}, {val}) set {varname} in window
1828 {winnr} in tab page {tabnr} to {val}
1829 setwinvar( {nr}, {varname}, {val}) set {varname} in window {nr} to {val}
1830 shellescape( {string}) String escape {string} for use as shell
1831 command argument
1832 simplify( {filename}) String simplify filename as much as possible
1833 sort( {list} [, {func}]) List sort {list}, using {func} to compare
1834 soundfold( {word}) String sound-fold {word}
1835 spellbadword() String badly spelled word at cursor
1836 spellsuggest( {word} [, {max} [, {capital}]])
1837 List spelling suggestions
1838 split( {expr} [, {pat} [, {keepempty}]])
1839 List make |List| from {pat} separated {expr}
1840 str2float( {expr}) Float convert String to Float
1841 str2nr( {expr} [, {base}]) Number convert String to Number
1842 strftime( {format}[, {time}]) String time in specified format
1843 stridx( {haystack}, {needle}[, {start}])
1844 Number index of {needle} in {haystack}
1845 string( {expr}) String String representation of {expr} value
1846 strlen( {expr}) Number length of the String {expr}
1847 strpart( {src}, {start}[, {len}])
1848 String {len} characters of {src} at {start}
1849 strridx( {haystack}, {needle} [, {start}])
1850 Number last index of {needle} in {haystack}
1851 strtrans( {expr}) String translate string to make it printable
1852 submatch( {nr}) String specific match in ":substitute"
1853 substitute( {expr}, {pat}, {sub}, {flags})
1854 String all {pat} in {expr} replaced with {sub}
1855 synID( {lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
1856 synIDattr( {synID}, {what} [, {mode}])
1857 String attribute {what} of syntax ID {synID}
1858 synIDtrans( {synID}) Number translated syntax ID of {synID}
1859 synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
1860 system( {expr} [, {input}]) String output of shell command/filter {expr}
1861 tabpagebuflist( [{arg}]) List list of buffer numbers in tab page
1862 tabpagenr( [{arg}]) Number number of current or last tab page
1863 tabpagewinnr( {tabarg}[, {arg}])
1864 Number number of current window in tab page
1865 taglist( {expr}) List list of tags matching {expr}
1866 tagfiles() List tags files used
1867 tempname() String name for a temporary file
1868 tolower( {expr}) String the String {expr} switched to lowercase
1869 toupper( {expr}) String the String {expr} switched to uppercase
1870 tr( {src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
1871 to chars in {tostr}
1872 trunc( {expr} Float truncate Float {expr}
1873 type( {name}) Number type of variable {name}
1874 values( {dict}) List values in {dict}
1875 virtcol( {expr}) Number screen column of cursor or mark
1876 visualmode( [expr]) String last visual mode used
1877 winbufnr( {nr}) Number buffer number of window {nr}
1878 wincol() Number window column of the cursor
1879 winheight( {nr}) Number height of window {nr}
1880 winline() Number window line of the cursor
1881 winnr( [{expr}]) Number number of current window
1882 winrestcmd() String returns command to restore window sizes
1883 winrestview({dict}) None restore view of current window
1884 winsaveview() Dict save view of current window
1885 winwidth( {nr}) Number width of window {nr}
1886 writefile({list}, {fname} [, {binary}])
1887 Number write list of lines to file {fname}
1889 add({list}, {expr}) *add()*
1890 Append the item {expr} to |List| {list}. Returns the
1891 resulting |List|. Examples: >
1892 :let alist = add([1, 2, 3], item)
1893 :call add(mylist, "woodstock")
1894 < Note that when {expr} is a |List| it is appended as a single
1895 item. Use |extend()| to concatenate |Lists|.
1896 Use |insert()| to add an item at another position.
1899 append({lnum}, {expr}) *append()*
1900 When {expr} is a |List|: Append each item of the |List| as a
1901 text line below line {lnum} in the current buffer.
1902 Otherwise append {expr} as one text line below line {lnum} in
1903 the current buffer.
1904 {lnum} can be zero to insert a line before the first one.
1905 Returns 1 for failure ({lnum} out of range or out of memory),
1906 0 for success. Example: >
1907 :let failed = append(line('$'), "# THE END")
1908 :let failed = append(0, ["Chapter 1", "the beginning"])
1909 <
1910 *argc()*
1911 argc() The result is the number of files in the argument list of the
1912 current window. See |arglist|.
1914 *argidx()*
1915 argidx() The result is the current index in the argument list. 0 is
1916 the first file. argc() - 1 is the last one. See |arglist|.
1918 *argv()*
1919 argv([{nr}]) The result is the {nr}th file in the argument list of the
1920 current window. See |arglist|. "argv(0)" is the first one.
1921 Example: >
1922 :let i = 0
1923 :while i < argc()
1924 : let f = escape(fnameescape(argv(i)), '.')
1925 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>'
1926 : let i = i + 1
1927 :endwhile
1928 < Without the {nr} argument a |List| with the whole |arglist| is
1929 returned.
1931 *browse()*
1932 browse({save}, {title}, {initdir}, {default})
1933 Put up a file requester. This only works when "has("browse")"
1934 returns non-zero (only in some GUI versions).
1935 The input fields are:
1936 {save} when non-zero, select file to write
1937 {title} title for the requester
1938 {initdir} directory to start browsing in
1939 {default} default file name
1940 When the "Cancel" button is hit, something went wrong, or
1941 browsing is not possible, an empty string is returned.
1943 *browsedir()*
1944 browsedir({title}, {initdir})
1945 Put up a directory requester. This only works when
1946 "has("browse")" returns non-zero (only in some GUI versions).
1947 On systems where a directory browser is not supported a file
1948 browser is used. In that case: select a file in the directory
1949 to be used.
1950 The input fields are:
1951 {title} title for the requester
1952 {initdir} directory to start browsing in
1953 When the "Cancel" button is hit, something went wrong, or
1954 browsing is not possible, an empty string is returned.
1956 bufexists({expr}) *bufexists()*
1957 The result is a Number, which is non-zero if a buffer called
1958 {expr} exists.
1959 If the {expr} argument is a number, buffer numbers are used.
1960 If the {expr} argument is a string it must match a buffer name
1961 exactly. The name can be:
1962 - Relative to the current directory.
1963 - A full path.
1964 - The name of a buffer with 'buftype' set to "nofile".
1965 - A URL name.
1966 Unlisted buffers will be found.
1967 Note that help files are listed by their short name in the
1968 output of |:buffers|, but bufexists() requires using their
1969 long name to be able to find them.
1970 bufexists() may report a buffer exists, but to use the name
1971 with a |:buffer| command you may need to use |expand()|. Esp
1972 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
1973 Use "bufexists(0)" to test for the existence of an alternate
1974 file name.
1975 *buffer_exists()*
1976 Obsolete name: buffer_exists().
1978 buflisted({expr}) *buflisted()*
1979 The result is a Number, which is non-zero if a buffer called
1980 {expr} exists and is listed (has the 'buflisted' option set).
1981 The {expr} argument is used like with |bufexists()|.
1983 bufloaded({expr}) *bufloaded()*
1984 The result is a Number, which is non-zero if a buffer called
1985 {expr} exists and is loaded (shown in a window or hidden).
1986 The {expr} argument is used like with |bufexists()|.
1988 bufname({expr}) *bufname()*
1989 The result is the name of a buffer, as it is displayed by the
1990 ":ls" command.
1991 If {expr} is a Number, that buffer number's name is given.
1992 Number zero is the alternate buffer for the current window.
1993 If {expr} is a String, it is used as a |file-pattern| to match
1994 with the buffer names. This is always done like 'magic' is
1995 set and 'cpoptions' is empty. When there is more than one
1996 match an empty string is returned.
1997 "" or "%" can be used for the current buffer, "#" for the
1998 alternate buffer.
1999 A full match is preferred, otherwise a match at the start, end
2000 or middle of the buffer name is accepted. If you only want a
2001 full match then put "^" at the start and "$" at the end of the
2002 pattern.
2003 Listed buffers are found first. If there is a single match
2004 with a listed buffer, that one is returned. Next unlisted
2005 buffers are searched for.
2006 If the {expr} is a String, but you want to use it as a buffer
2007 number, force it to be a Number by adding zero to it: >
2008 :echo bufname("3" + 0)
2009 < If the buffer doesn't exist, or doesn't have a name, an empty
2010 string is returned. >
2011 bufname("#") alternate buffer name
2012 bufname(3) name of buffer 3
2013 bufname("%") name of current buffer
2014 bufname("file2") name of buffer where "file2" matches.
2015 < *buffer_name()*
2016 Obsolete name: buffer_name().
2018 *bufnr()*
2019 bufnr({expr} [, {create}])
2020 The result is the number of a buffer, as it is displayed by
2021 the ":ls" command. For the use of {expr}, see |bufname()|
2022 above.
2023 If the buffer doesn't exist, -1 is returned. Or, if the
2024 {create} argument is present and not zero, a new, unlisted,
2025 buffer is created and its number is returned.
2026 bufnr("$") is the last buffer: >
2027 :let last_buffer = bufnr("$")
2028 < The result is a Number, which is the highest buffer number
2029 of existing buffers. Note that not all buffers with a smaller
2030 number necessarily exist, because ":bwipeout" may have removed
2031 them. Use bufexists() to test for the existence of a buffer.
2032 *buffer_number()*
2033 Obsolete name: buffer_number().
2034 *last_buffer_nr()*
2035 Obsolete name for bufnr("$"): last_buffer_nr().
2037 bufwinnr({expr}) *bufwinnr()*
2038 The result is a Number, which is the number of the first
2039 window associated with buffer {expr}. For the use of {expr},
2040 see |bufname()| above. If buffer {expr} doesn't exist or
2041 there is no such window, -1 is returned. Example: >
2043 echo "A window containing buffer 1 is " . (bufwinnr(1))
2045 < The number can be used with |CTRL-W_w| and ":wincmd w"
2046 |:wincmd|.
2047 Only deals with the current tab page.
2050 byte2line({byte}) *byte2line()*
2051 Return the line number that contains the character at byte
2052 count {byte} in the current buffer. This includes the
2053 end-of-line character, depending on the 'fileformat' option
2054 for the current buffer. The first character has byte count
2055 one.
2056 Also see |line2byte()|, |go| and |:goto|.
2057 {not available when compiled without the |+byte_offset|
2058 feature}
2060 byteidx({expr}, {nr}) *byteidx()*
2061 Return byte index of the {nr}'th character in the string
2062 {expr}. Use zero for the first character, it returns zero.
2063 This function is only useful when there are multibyte
2064 characters, otherwise the returned value is equal to {nr}.
2065 Composing characters are counted as a separate character.
2066 Example : >
2067 echo matchstr(str, ".", byteidx(str, 3))
2068 < will display the fourth character. Another way to do the
2069 same: >
2070 let s = strpart(str, byteidx(str, 3))
2071 echo strpart(s, 0, byteidx(s, 1))
2072 < If there are less than {nr} characters -1 is returned.
2073 If there are exactly {nr} characters the length of the string
2074 is returned.
2076 call({func}, {arglist} [, {dict}]) *call()* *E699*
2077 Call function {func} with the items in |List| {arglist} as
2078 arguments.
2079 {func} can either be a |Funcref| or the name of a function.
2080 a:firstline and a:lastline are set to the cursor line.
2081 Returns the return value of the called function.
2082 {dict} is for functions with the "dict" attribute. It will be
2083 used to set the local variable "self". |Dictionary-function|
2085 ceil({expr}) *ceil()*
2086 Return the smallest integral value greater than or equal to
2087 {expr} as a |Float| (round up).
2088 {expr} must evaluate to a |Float| or a |Number|.
2089 Examples: >
2090 echo ceil(1.456)
2091 < 2.0 >
2092 echo ceil(-5.456)
2093 < -5.0 >
2094 echo ceil(4.0)
2095 < 4.0
2096 {only available when compiled with the |+float| feature}
2098 changenr() *changenr()*
2099 Return the number of the most recent change. This is the same
2100 number as what is displayed with |:undolist| and can be used
2101 with the |:undo| command.
2102 When a change was made it is the number of that change. After
2103 redo it is the number of the redone change. After undo it is
2104 one less than the number of the undone change.
2106 char2nr({expr}) *char2nr()*
2107 Return number value of the first char in {expr}. Examples: >
2108 char2nr(" ") returns 32
2109 char2nr("ABC") returns 65
2110 < The current 'encoding' is used. Example for "utf-8": >
2111 char2nr("á") returns 225
2112 char2nr("á"[0]) returns 195
2113 < |nr2char()| does the opposite.
2115 cindent({lnum}) *cindent()*
2116 Get the amount of indent for line {lnum} according the C
2117 indenting rules, as with 'cindent'.
2118 The indent is counted in spaces, the value of 'tabstop' is
2119 relevant. {lnum} is used just like in |getline()|.
2120 When {lnum} is invalid or Vim was not compiled the |+cindent|
2121 feature, -1 is returned.
2122 See |C-indenting|.
2124 clearmatches() *clearmatches()*
2125 Clears all matches previously defined by |matchadd()| and the
2126 |:match| commands.
2128 *col()*
2129 col({expr}) The result is a Number, which is the byte index of the column
2130 position given with {expr}. The accepted positions are:
2131 . the cursor position
2132 $ the end of the cursor line (the result is the
2133 number of characters in the cursor line plus one)
2134 'x position of mark x (if the mark is not set, 0 is
2135 returned)
2136 Additionally {expr} can be [lnum, col]: a |List| with the line
2137 and column number. Most useful when the column is "$", to get
2138 the last column of a specific line. When "lnum" or "col" is
2139 out of range then col() returns zero.
2140 To get the line number use |line()|. To get both use
2141 |getpos()|.
2142 For the screen column position use |virtcol()|.
2143 Note that only marks in the current file can be used.
2144 Examples: >
2145 col(".") column of cursor
2146 col("$") length of cursor line plus one
2147 col("'t") column of mark t
2148 col("'" . markname) column of mark markname
2149 < The first column is 1. 0 is returned for an error.
2150 For an uppercase mark the column may actually be in another
2151 buffer.
2152 For the cursor position, when 'virtualedit' is active, the
2153 column is one higher if the cursor is after the end of the
2154 line. This can be used to obtain the column in Insert mode: >
2155 :imap <F2> <C-O>:let save_ve = &ve<CR>
2156 \<C-O>:set ve=all<CR>
2157 \<C-O>:echo col(".") . "\n" <Bar>
2158 \let &ve = save_ve<CR>
2159 <
2161 complete({startcol}, {matches}) *complete()* *E785*
2162 Set the matches for Insert mode completion.
2163 Can only be used in Insert mode. You need to use a mapping
2164 with CTRL-R = |i_CTRL-R|. It does not work after CTRL-O or
2165 with an expression mapping.
2166 {startcol} is the byte offset in the line where the completed
2167 text start. The text up to the cursor is the original text
2168 that will be replaced by the matches. Use col('.') for an
2169 empty string. "col('.') - 1" will replace one character by a
2170 match.
2171 {matches} must be a |List|. Each |List| item is one match.
2172 See |complete-items| for the kind of items that are possible.
2173 Note that the after calling this function you need to avoid
2174 inserting anything that would completion to stop.
2175 The match can be selected with CTRL-N and CTRL-P as usual with
2176 Insert mode completion. The popup menu will appear if
2177 specified, see |ins-completion-menu|.
2178 Example: >
2179 inoremap <F5> <C-R>=ListMonths()<CR>
2181 func! ListMonths()
2182 call complete(col('.'), ['January', 'February', 'March',
2183 \ 'April', 'May', 'June', 'July', 'August', 'September',
2184 \ 'October', 'November', 'December'])
2185 return ''
2186 endfunc
2187 < This isn't very useful, but it shows how it works. Note that
2188 an empty string is returned to avoid a zero being inserted.
2190 complete_add({expr}) *complete_add()*
2191 Add {expr} to the list of matches. Only to be used by the
2192 function specified with the 'completefunc' option.
2193 Returns 0 for failure (empty string or out of memory),
2194 1 when the match was added, 2 when the match was already in
2195 the list.
2196 See |complete-functions| for an explanation of {expr}. It is
2197 the same as one item in the list that 'omnifunc' would return.
2199 complete_check() *complete_check()*
2200 Check for a key typed while looking for completion matches.
2201 This is to be used when looking for matches takes some time.
2202 Returns non-zero when searching for matches is to be aborted,
2203 zero otherwise.
2204 Only to be used by the function specified with the
2205 'completefunc' option.
2207 *confirm()*
2208 confirm({msg} [, {choices} [, {default} [, {type}]]])
2209 Confirm() offers the user a dialog, from which a choice can be
2210 made. It returns the number of the choice. For the first
2211 choice this is 1.
2212 Note: confirm() is only supported when compiled with dialog
2213 support, see |+dialog_con| and |+dialog_gui|.
2214 {msg} is displayed in a |dialog| with {choices} as the
2215 alternatives. When {choices} is missing or empty, "&OK" is
2216 used (and translated).
2217 {msg} is a String, use '\n' to include a newline. Only on
2218 some systems the string is wrapped when it doesn't fit.
2219 {choices} is a String, with the individual choices separated
2220 by '\n', e.g. >
2221 confirm("Save changes?", "&Yes\n&No\n&Cancel")
2222 < The letter after the '&' is the shortcut key for that choice.
2223 Thus you can type 'c' to select "Cancel". The shortcut does
2224 not need to be the first letter: >
2225 confirm("file has been modified", "&Save\nSave &All")
2226 < For the console, the first letter of each choice is used as
2227 the default shortcut key.
2228 The optional {default} argument is the number of the choice
2229 that is made if the user hits <CR>. Use 1 to make the first
2230 choice the default one. Use 0 to not set a default. If
2231 {default} is omitted, 1 is used.
2232 The optional {type} argument gives the type of dialog. This
2233 is only used for the icon of the Win32 GUI. It can be one of
2234 these values: "Error", "Question", "Info", "Warning" or
2235 "Generic". Only the first character is relevant. When {type}
2236 is omitted, "Generic" is used.
2237 If the user aborts the dialog by pressing <Esc>, CTRL-C,
2238 or another valid interrupt key, confirm() returns 0.
2240 An example: >
2241 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2)
2242 :if choice == 0
2243 : echo "make up your mind!"
2244 :elseif choice == 3
2245 : echo "tasteful"
2246 :else
2247 : echo "I prefer bananas myself."
2248 :endif
2249 < In a GUI dialog, buttons are used. The layout of the buttons
2250 depends on the 'v' flag in 'guioptions'. If it is included,
2251 the buttons are always put vertically. Otherwise, confirm()
2252 tries to put the buttons in one horizontal line. If they
2253 don't fit, a vertical layout is used anyway. For some systems
2254 the horizontal layout is always used.
2256 *copy()*
2257 copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
2258 different from using {expr} directly.
2259 When {expr} is a |List| a shallow copy is created. This means
2260 that the original |List| can be changed without changing the
2261 copy, and vice versa. But the items are identical, thus
2262 changing an item changes the contents of both |Lists|. Also
2263 see |deepcopy()|.
2265 count({comp}, {expr} [, {ic} [, {start}]]) *count()*
2266 Return the number of times an item with value {expr} appears
2267 in |List| or |Dictionary| {comp}.
2268 If {start} is given then start with the item with this index.
2269 {start} can only be used with a |List|.
2270 When {ic} is given and it's non-zero then case is ignored.
2273 *cscope_connection()*
2274 cscope_connection([{num} , {dbpath} [, {prepend}]])
2275 Checks for the existence of a |cscope| connection. If no
2276 parameters are specified, then the function returns:
2277 0, if cscope was not available (not compiled in), or
2278 if there are no cscope connections;
2279 1, if there is at least one cscope connection.
2281 If parameters are specified, then the value of {num}
2282 determines how existence of a cscope connection is checked:
2284 {num} Description of existence check
2285 ----- ------------------------------
2286 0 Same as no parameters (e.g., "cscope_connection()").
2287 1 Ignore {prepend}, and use partial string matches for
2288 {dbpath}.
2289 2 Ignore {prepend}, and use exact string matches for
2290 {dbpath}.
2291 3 Use {prepend}, use partial string matches for both
2292 {dbpath} and {prepend}.
2293 4 Use {prepend}, use exact string matches for both
2294 {dbpath} and {prepend}.
2296 Note: All string comparisons are case sensitive!
2298 Examples. Suppose we had the following (from ":cs show"): >
2300 # pid database name prepend path
2301 0 27664 cscope.out /usr/local
2302 <
2303 Invocation Return Val ~
2304 ---------- ---------- >
2305 cscope_connection() 1
2306 cscope_connection(1, "out") 1
2307 cscope_connection(2, "out") 0
2308 cscope_connection(3, "out") 0
2309 cscope_connection(3, "out", "local") 1
2310 cscope_connection(4, "out") 0
2311 cscope_connection(4, "out", "local") 0
2312 cscope_connection(4, "cscope.out", "/usr/local") 1
2313 <
2314 cursor({lnum}, {col} [, {off}]) *cursor()*
2315 cursor({list})
2316 Positions the cursor at the column (byte count) {col} in the
2317 line {lnum}. The first column is one.
2318 When there is one argument {list} this is used as a |List|
2319 with two or three items {lnum}, {col} and {off}. This is like
2320 the return value of |getpos()|, but without the first item.
2321 Does not change the jumplist.
2322 If {lnum} is greater than the number of lines in the buffer,
2323 the cursor will be positioned at the last line in the buffer.
2324 If {lnum} is zero, the cursor will stay in the current line.
2325 If {col} is greater than the number of bytes in the line,
2326 the cursor will be positioned at the last character in the
2327 line.
2328 If {col} is zero, the cursor will stay in the current column.
2329 When 'virtualedit' is used {off} specifies the offset in
2330 screen columns from the start of the character. E.g., a
2331 position within a <Tab> or after the last character.
2334 deepcopy({expr}[, {noref}]) *deepcopy()* *E698*
2335 Make a copy of {expr}. For Numbers and Strings this isn't
2336 different from using {expr} directly.
2337 When {expr} is a |List| a full copy is created. This means
2338 that the original |List| can be changed without changing the
2339 copy, and vice versa. When an item is a |List|, a copy for it
2340 is made, recursively. Thus changing an item in the copy does
2341 not change the contents of the original |List|.
2342 When {noref} is omitted or zero a contained |List| or
2343 |Dictionary| is only copied once. All references point to
2344 this single copy. With {noref} set to 1 every occurrence of a
2345 |List| or |Dictionary| results in a new copy. This also means
2346 that a cyclic reference causes deepcopy() to fail.
2347 *E724*
2348 Nesting is possible up to 100 levels. When there is an item
2349 that refers back to a higher level making a deep copy with
2350 {noref} set to 1 will fail.
2351 Also see |copy()|.
2353 delete({fname}) *delete()*
2354 Deletes the file by the name {fname}. The result is a Number,
2355 which is 0 if the file was deleted successfully, and non-zero
2356 when the deletion failed.
2357 Use |remove()| to delete an item from a |List|.
2359 *did_filetype()*
2360 did_filetype() Returns non-zero when autocommands are being executed and the
2361 FileType event has been triggered at least once. Can be used
2362 to avoid triggering the FileType event again in the scripts
2363 that detect the file type. |FileType|
2364 When editing another file, the counter is reset, thus this
2365 really checks if the FileType event has been triggered for the
2366 current buffer. This allows an autocommand that starts
2367 editing another buffer to set 'filetype' and load a syntax
2368 file.
2370 diff_filler({lnum}) *diff_filler()*
2371 Returns the number of filler lines above line {lnum}.
2372 These are the lines that were inserted at this point in
2373 another diff'ed window. These filler lines are shown in the
2374 display but don't exist in the buffer.
2375 {lnum} is used like with |getline()|. Thus "." is the current
2376 line, "'m" mark m, etc.
2377 Returns 0 if the current window is not in diff mode.
2379 diff_hlID({lnum}, {col}) *diff_hlID()*
2380 Returns the highlight ID for diff mode at line {lnum} column
2381 {col} (byte index). When the current line does not have a
2382 diff change zero is returned.
2383 {lnum} is used like with |getline()|. Thus "." is the current
2384 line, "'m" mark m, etc.
2385 {col} is 1 for the leftmost column, {lnum} is 1 for the first
2386 line.
2387 The highlight ID can be used with |synIDattr()| to obtain
2388 syntax information about the highlighting.
2390 empty({expr}) *empty()*
2391 Return the Number 1 if {expr} is empty, zero otherwise.
2392 A |List| or |Dictionary| is empty when it does not have any
2393 items. A Number is empty when its value is zero.
2394 For a long |List| this is much faster then comparing the
2395 length with zero.
2397 escape({string}, {chars}) *escape()*
2398 Escape the characters in {chars} that occur in {string} with a
2399 backslash. Example: >
2400 :echo escape('c:\program files\vim', ' \')
2401 < results in: >
2402 c:\\program\ files\\vim
2403 < Also see |shellescape()|.
2405 *eval()*
2406 eval({string}) Evaluate {string} and return the result. Especially useful to
2407 turn the result of |string()| back into the original value.
2408 This works for Numbers, Floats, Strings and composites of
2409 them. Also works for |Funcref|s that refer to existing
2410 functions.
2412 eventhandler() *eventhandler()*
2413 Returns 1 when inside an event handler. That is that Vim got
2414 interrupted while waiting for the user to type a character,
2415 e.g., when dropping a file on Vim. This means interactive
2416 commands cannot be used. Otherwise zero is returned.
2418 executable({expr}) *executable()*
2419 This function checks if an executable with the name {expr}
2420 exists. {expr} must be the name of the program without any
2421 arguments.
2422 executable() uses the value of $PATH and/or the normal
2423 searchpath for programs. *PATHEXT*
2424 On MS-DOS and MS-Windows the ".exe", ".bat", etc. can
2425 optionally be included. Then the extensions in $PATHEXT are
2426 tried. Thus if "foo.exe" does not exist, "foo.exe.bat" can be
2427 found. If $PATHEXT is not set then ".exe;.com;.bat;.cmd" is
2428 used. A dot by itself can be used in $PATHEXT to try using
2429 the name without an extension. When 'shell' looks like a
2430 Unix shell, then the name is also tried without adding an
2431 extension.
2432 On MS-DOS and MS-Windows it only checks if the file exists and
2433 is not a directory, not if it's really executable.
2434 On MS-Windows an executable in the same directory as Vim is
2435 always found. Since this directory is added to $PATH it
2436 should also work to execute it |win32-PATH|.
2437 The result is a Number:
2438 1 exists
2439 0 does not exist
2440 -1 not implemented on this system
2442 *exists()*
2443 exists({expr}) The result is a Number, which is non-zero if {expr} is
2444 defined, zero otherwise. The {expr} argument is a string,
2445 which contains one of these:
2446 &option-name Vim option (only checks if it exists,
2447 not if it really works)
2448 +option-name Vim option that works.
2449 $ENVNAME environment variable (could also be
2450 done by comparing with an empty
2451 string)
2452 *funcname built-in function (see |functions|)
2453 or user defined function (see
2454 |user-functions|).
2455 varname internal variable (see
2456 |internal-variables|). Also works
2457 for |curly-braces-names|, |Dictionary|
2458 entries, |List| items, etc. Beware
2459 that this may cause functions to be
2460 invoked cause an error message for an
2461 invalid expression.
2462 :cmdname Ex command: built-in command, user
2463 command or command modifier |:command|.
2464 Returns:
2465 1 for match with start of a command
2466 2 full match with a command
2467 3 matches several user commands
2468 To check for a supported command
2469 always check the return value to be 2.
2470 :2match The |:2match| command.
2471 :3match The |:3match| command.
2472 #event autocommand defined for this event
2473 #event#pattern autocommand defined for this event and
2474 pattern (the pattern is taken
2475 literally and compared to the
2476 autocommand patterns character by
2477 character)
2478 #group autocommand group exists
2479 #group#event autocommand defined for this group and
2480 event.
2481 #group#event#pattern
2482 autocommand defined for this group,
2483 event and pattern.
2484 ##event autocommand for this event is
2485 supported.
2486 For checking for a supported feature use |has()|.
2488 Examples: >
2489 exists("&shortname")
2490 exists("$HOSTNAME")
2491 exists("*strftime")
2492 exists("*s:MyFunc")
2493 exists("bufcount")
2494 exists(":Make")
2495 exists("#CursorHold")
2496 exists("#BufReadPre#*.gz")
2497 exists("#filetypeindent")
2498 exists("#filetypeindent#FileType")
2499 exists("#filetypeindent#FileType#*")
2500 exists("##ColorScheme")
2501 < There must be no space between the symbol (&/$/*/#) and the
2502 name.
2503 There must be no extra characters after the name, although in
2504 a few cases this is ignored. That may become more strict in
2505 the future, thus don't count on it!
2506 Working example: >
2507 exists(":make")
2508 < NOT working example: >
2509 exists(":make install")
2511 < Note that the argument must be a string, not the name of the
2512 variable itself. For example: >
2513 exists(bufcount)
2514 < This doesn't check for existence of the "bufcount" variable,
2515 but gets the value of "bufcount", and checks if that exists.
2517 expand({expr} [, {flag}]) *expand()*
2518 Expand wildcards and the following special keywords in {expr}.
2519 The result is a String.
2521 When there are several matches, they are separated by <NL>
2522 characters. [Note: in version 5.0 a space was used, which
2523 caused problems when a file name contains a space]
2525 If the expansion fails, the result is an empty string. A name
2526 for a non-existing file is not included.
2528 When {expr} starts with '%', '#' or '<', the expansion is done
2529 like for the |cmdline-special| variables with their associated
2530 modifiers. Here is a short overview:
2532 % current file name
2533 # alternate file name
2534 #n alternate file name n
2535 <cfile> file name under the cursor
2536 <afile> autocmd file name
2537 <abuf> autocmd buffer number (as a String!)
2538 <amatch> autocmd matched name
2539 <sfile> sourced script file name
2540 <cword> word under the cursor
2541 <cWORD> WORD under the cursor
2542 <client> the {clientid} of the last received
2543 message |server2client()|
2544 Modifiers:
2545 :p expand to full path
2546 :h head (last path component removed)
2547 :t tail (last path component only)
2548 :r root (one extension removed)
2549 :e extension only
2551 Example: >
2552 :let &tags = expand("%:p:h") . "/tags"
2553 < Note that when expanding a string that starts with '%', '#' or
2554 '<', any following text is ignored. This does NOT work: >
2555 :let doesntwork = expand("%:h.bak")
2556 < Use this: >
2557 :let doeswork = expand("%:h") . ".bak"
2558 < Also note that expanding "<cfile>" and others only returns the
2559 referenced file name without further expansion. If "<cfile>"
2560 is "~/.cshrc", you need to do another expand() to have the
2561 "~/" expanded into the path of the home directory: >
2562 :echo expand(expand("<cfile>"))
2563 <
2564 There cannot be white space between the variables and the
2565 following modifier. The |fnamemodify()| function can be used
2566 to modify normal file names.
2568 When using '%' or '#', and the current or alternate file name
2569 is not defined, an empty string is used. Using "%:p" in a
2570 buffer with no name, results in the current directory, with a
2571 '/' added.
2573 When {expr} does not start with '%', '#' or '<', it is
2574 expanded like a file name is expanded on the command line.
2575 'suffixes' and 'wildignore' are used, unless the optional
2576 {flag} argument is given and it is non-zero. Names for
2577 non-existing files are included. The "**" item can be used to
2578 search in a directory tree. For example, to find all "README"
2579 files in the current directory and below: >
2580 :echo expand("**/README")
2581 <
2582 Expand() can also be used to expand variables and environment
2583 variables that are only known in a shell. But this can be
2584 slow, because a shell must be started. See |expr-env-expand|.
2585 The expanded variable is still handled like a list of file
2586 names. When an environment variable cannot be expanded, it is
2587 left unchanged. Thus ":echo expand('$FOOBAR')" results in
2588 "$FOOBAR".
2590 See |glob()| for finding existing files. See |system()| for
2591 getting the raw output of an external command.
2593 extend({expr1}, {expr2} [, {expr3}]) *extend()*
2594 {expr1} and {expr2} must be both |Lists| or both
2595 |Dictionaries|.
2597 If they are |Lists|: Append {expr2} to {expr1}.
2598 If {expr3} is given insert the items of {expr2} before item
2599 {expr3} in {expr1}. When {expr3} is zero insert before the
2600 first item. When {expr3} is equal to len({expr1}) then
2601 {expr2} is appended.
2602 Examples: >
2603 :echo sort(extend(mylist, [7, 5]))
2604 :call extend(mylist, [2, 3], 1)
2605 < Use |add()| to concatenate one item to a list. To concatenate
2606 two lists into a new list use the + operator: >
2607 :let newlist = [1, 2, 3] + [4, 5]
2608 <
2609 If they are |Dictionaries|:
2610 Add all entries from {expr2} to {expr1}.
2611 If a key exists in both {expr1} and {expr2} then {expr3} is
2612 used to decide what to do:
2613 {expr3} = "keep": keep the value of {expr1}
2614 {expr3} = "force": use the value of {expr2}
2615 {expr3} = "error": give an error message *E737*
2616 When {expr3} is omitted then "force" is assumed.
2618 {expr1} is changed when {expr2} is not empty. If necessary
2619 make a copy of {expr1} first.
2620 {expr2} remains unchanged.
2621 Returns {expr1}.
2624 feedkeys({string} [, {mode}]) *feedkeys()*
2625 Characters in {string} are queued for processing as if they
2626 come from a mapping or were typed by the user. They are added
2627 to the end of the typeahead buffer, thus if a mapping is still
2628 being executed these characters come after them.
2629 The function does not wait for processing of keys contained in
2630 {string}.
2631 To include special keys into {string}, use double-quotes
2632 and "\..." notation |expr-quote|. For example,
2633 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
2634 feedkeys('\<CR>') pushes 5 characters.
2635 If {mode} is absent, keys are remapped.
2636 {mode} is a String, which can contain these character flags:
2637 'm' Remap keys. This is default.
2638 'n' Do not remap keys.
2639 't' Handle keys as if typed; otherwise they are handled as
2640 if coming from a mapping. This matters for undo,
2641 opening folds, etc.
2642 Return value is always 0.
2644 filereadable({file}) *filereadable()*
2645 The result is a Number, which is TRUE when a file with the
2646 name {file} exists, and can be read. If {file} doesn't exist,
2647 or is a directory, the result is FALSE. {file} is any
2648 expression, which is used as a String.
2649 If you don't care about the file being readable you can use
2650 |glob()|.
2651 *file_readable()*
2652 Obsolete name: file_readable().
2655 filewritable({file}) *filewritable()*
2656 The result is a Number, which is 1 when a file with the
2657 name {file} exists, and can be written. If {file} doesn't
2658 exist, or is not writable, the result is 0. If {file} is a
2659 directory, and we can write to it, the result is 2.
2662 filter({expr}, {string}) *filter()*
2663 {expr} must be a |List| or a |Dictionary|.
2664 For each item in {expr} evaluate {string} and when the result
2665 is zero remove the item from the |List| or |Dictionary|.
2666 Inside {string} |v:val| has the value of the current item.
2667 For a |Dictionary| |v:key| has the key of the current item.
2668 Examples: >
2669 :call filter(mylist, 'v:val !~ "OLD"')
2670 < Removes the items where "OLD" appears. >
2671 :call filter(mydict, 'v:key >= 8')
2672 < Removes the items with a key below 8. >
2673 :call filter(var, 0)
2674 < Removes all the items, thus clears the |List| or |Dictionary|.
2676 Note that {string} is the result of expression and is then
2677 used as an expression again. Often it is good to use a
2678 |literal-string| to avoid having to double backslashes.
2680 The operation is done in-place. If you want a |List| or
2681 |Dictionary| to remain unmodified make a copy first: >
2682 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
2684 < Returns {expr}, the |List| or |Dictionary| that was filtered.
2685 When an error is encountered while evaluating {string} no
2686 further items in {expr} are processed.
2689 finddir({name}[, {path}[, {count}]]) *finddir()*
2690 Find directory {name} in {path}. Supports both downwards and
2691 upwards recursive directory searches. See |file-searching|
2692 for the syntax of {path}.
2693 Returns the path of the first found match. When the found
2694 directory is below the current directory a relative path is
2695 returned. Otherwise a full path is returned.
2696 If {path} is omitted or empty then 'path' is used.
2697 If the optional {count} is given, find {count}'s occurrence of
2698 {name} in {path} instead of the first one.
2699 When {count} is negative return all the matches in a |List|.
2700 This is quite similar to the ex-command |:find|.
2701 {only available when compiled with the +file_in_path feature}
2703 findfile({name}[, {path}[, {count}]]) *findfile()*
2704 Just like |finddir()|, but find a file instead of a directory.
2705 Uses 'suffixesadd'.
2706 Example: >
2707 :echo findfile("tags.vim", ".;")
2708 < Searches from the directory of the current file upwards until
2709 it finds the file "tags.vim".
2711 float2nr({expr}) *float2nr()*
2712 Convert {expr} to a Number by omitting the part after the
2713 decimal point.
2714 {expr} must evaluate to a |Float| or a Number.
2715 When the value of {expr} is out of range for a |Number| the
2716 result is truncated to 0x7fffffff or -0x7fffffff.
2717 Examples: >
2718 echo float2nr(3.95)
2719 < 3 >
2720 echo float2nr(-23.45)
2721 < -23 >
2722 echo float2nr(1.0e100)
2723 < 2147483647 >
2724 echo float2nr(-1.0e150)
2725 < -2147483647 >
2726 echo float2nr(1.0e-100)
2727 < 0
2728 {only available when compiled with the |+float| feature}
2731 floor({expr}) *floor()*
2732 Return the largest integral value less than or equal to
2733 {expr} as a |Float| (round down).
2734 {expr} must evaluate to a |Float| or a |Number|.
2735 Examples: >
2736 echo floor(1.856)
2737 < 1.0 >
2738 echo floor(-5.456)
2739 < -6.0 >
2740 echo floor(4.0)
2741 < 4.0
2742 {only available when compiled with the |+float| feature}
2744 fnameescape({string}) *fnameescape()*
2745 Escape {string} for use as file name command argument. All
2746 characters that have a special meaning, such as '%' and '|'
2747 are escaped with a backslash.
2748 For most systems the characters escaped are
2749 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
2750 appears in a filename, it depends on the value of 'isfname'.
2751 Example: >
2752 :let fname = 'some str%nge|name'
2753 :exe "edit " . fnameescape(fname)
2754 < results in executing: >
2755 edit some\ str\%nge\|name
2757 fnamemodify({fname}, {mods}) *fnamemodify()*
2758 Modify file name {fname} according to {mods}. {mods} is a
2759 string of characters like it is used for file names on the
2760 command line. See |filename-modifiers|.
2761 Example: >
2762 :echo fnamemodify("main.c", ":p:h")
2763 < results in: >
2764 /home/mool/vim/vim/src
2765 < Note: Environment variables don't work in {fname}, use
2766 |expand()| first then.
2768 foldclosed({lnum}) *foldclosed()*
2769 The result is a Number. If the line {lnum} is in a closed
2770 fold, the result is the number of the first line in that fold.
2771 If the line {lnum} is not in a closed fold, -1 is returned.
2773 foldclosedend({lnum}) *foldclosedend()*
2774 The result is a Number. If the line {lnum} is in a closed
2775 fold, the result is the number of the last line in that fold.
2776 If the line {lnum} is not in a closed fold, -1 is returned.
2778 foldlevel({lnum}) *foldlevel()*
2779 The result is a Number, which is the foldlevel of line {lnum}
2780 in the current buffer. For nested folds the deepest level is
2781 returned. If there is no fold at line {lnum}, zero is
2782 returned. It doesn't matter if the folds are open or closed.
2783 When used while updating folds (from 'foldexpr') -1 is
2784 returned for lines where folds are still to be updated and the
2785 foldlevel is unknown. As a special case the level of the
2786 previous line is usually available.
2788 *foldtext()*
2789 foldtext() Returns a String, to be displayed for a closed fold. This is
2790 the default function used for the 'foldtext' option and should
2791 only be called from evaluating 'foldtext'. It uses the
2792 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
2793 The returned string looks like this: >
2794 +-- 45 lines: abcdef
2795 < The number of dashes depends on the foldlevel. The "45" is
2796 the number of lines in the fold. "abcdef" is the text in the
2797 first non-blank line of the fold. Leading white space, "//"
2798 or "/*" and the text from the 'foldmarker' and 'commentstring'
2799 options is removed.
2800 {not available when compiled without the |+folding| feature}
2802 foldtextresult({lnum}) *foldtextresult()*
2803 Returns the text that is displayed for the closed fold at line
2804 {lnum}. Evaluates 'foldtext' in the appropriate context.
2805 When there is no closed fold at {lnum} an empty string is
2806 returned.
2807 {lnum} is used like with |getline()|. Thus "." is the current
2808 line, "'m" mark m, etc.
2809 Useful when exporting folded text, e.g., to HTML.
2810 {not available when compiled without the |+folding| feature}
2812 *foreground()*
2813 foreground() Move the Vim window to the foreground. Useful when sent from
2814 a client to a Vim server. |remote_send()|
2815 On Win32 systems this might not work, the OS does not always
2816 allow a window to bring itself to the foreground. Use
2817 |remote_foreground()| instead.
2818 {only in the Win32, Athena, Motif and GTK GUI versions and the
2819 Win32 console version}
2822 function({name}) *function()* *E700*
2823 Return a |Funcref| variable that refers to function {name}.
2824 {name} can be a user defined function or an internal function.
2827 garbagecollect([at_exit]) *garbagecollect()*
2828 Cleanup unused |Lists| and |Dictionaries| that have circular
2829 references. There is hardly ever a need to invoke this
2830 function, as it is automatically done when Vim runs out of
2831 memory or is waiting for the user to press a key after
2832 'updatetime'. Items without circular references are always
2833 freed when they become unused.
2834 This is useful if you have deleted a very big |List| and/or
2835 |Dictionary| with circular references in a script that runs
2836 for a long time.
2837 When the optional "at_exit" argument is one, garbage
2838 collection will also be done when exiting Vim, if it wasn't
2839 done before. This is useful when checking for memory leaks.
2841 get({list}, {idx} [, {default}]) *get()*
2842 Get item {idx} from |List| {list}. When this item is not
2843 available return {default}. Return zero when {default} is
2844 omitted.
2845 get({dict}, {key} [, {default}])
2846 Get item with key {key} from |Dictionary| {dict}. When this
2847 item is not available return {default}. Return zero when
2848 {default} is omitted.
2850 *getbufline()*
2851 getbufline({expr}, {lnum} [, {end}])
2852 Return a |List| with the lines starting from {lnum} to {end}
2853 (inclusive) in the buffer {expr}. If {end} is omitted, a
2854 |List| with only the line {lnum} is returned.
2856 For the use of {expr}, see |bufname()| above.
2858 For {lnum} and {end} "$" can be used for the last line of the
2859 buffer. Otherwise a number must be used.
2861 When {lnum} is smaller than 1 or bigger than the number of
2862 lines in the buffer, an empty |List| is returned.
2864 When {end} is greater than the number of lines in the buffer,
2865 it is treated as {end} is set to the number of lines in the
2866 buffer. When {end} is before {lnum} an empty |List| is
2867 returned.
2869 This function works only for loaded buffers. For unloaded and
2870 non-existing buffers, an empty |List| is returned.
2872 Example: >
2873 :let lines = getbufline(bufnr("myfile"), 1, "$")
2875 getbufvar({expr}, {varname}) *getbufvar()*
2876 The result is the value of option or local buffer variable
2877 {varname} in buffer {expr}. Note that the name without "b:"
2878 must be used.
2879 This also works for a global or buffer-local option, but it
2880 doesn't work for a global variable, window-local variable or
2881 window-local option.
2882 For the use of {expr}, see |bufname()| above.
2883 When the buffer or variable doesn't exist an empty string is
2884 returned, there is no error message.
2885 Examples: >
2886 :let bufmodified = getbufvar(1, "&mod")
2887 :echo "todo myvar = " . getbufvar("todo", "myvar")
2888 <
2889 getchar([expr]) *getchar()*
2890 Get a single character from the user or input stream.
2891 If [expr] is omitted, wait until a character is available.
2892 If [expr] is 0, only get a character when one is available.
2893 Return zero otherwise.
2894 If [expr] is 1, only check if a character is available, it is
2895 not consumed. Return zero if no character available.
2897 Without {expr} and when {expr} is 0 a whole character or
2898 special key is returned. If it is an 8-bit character, the
2899 result is a number. Use nr2char() to convert it to a String.
2900 Otherwise a String is returned with the encoded character.
2901 For a special key it's a sequence of bytes starting with 0x80
2902 (decimal: 128). This is the same value as the string
2903 "\<Key>", e.g., "\<Left>". The returned value is also a
2904 String when a modifier (shift, control, alt) was used that is
2905 not included in the character.
2907 When {expr} is 1 only the first byte is returned. For a
2908 one-byte character it is the character itself as a number.
2909 Use nr2char() to convert it to a String.
2911 When the user clicks a mouse button, the mouse event will be
2912 returned. The position can then be found in |v:mouse_col|,
2913 |v:mouse_lnum| and |v:mouse_win|. This example positions the
2914 mouse as it would normally happen: >
2915 let c = getchar()
2916 if c == "\<LeftMouse>" && v:mouse_win > 0
2917 exe v:mouse_win . "wincmd w"
2918 exe v:mouse_lnum
2919 exe "normal " . v:mouse_col . "|"
2920 endif
2921 <
2922 There is no prompt, you will somehow have to make clear to the
2923 user that a character has to be typed.
2924 There is no mapping for the character.
2925 Key codes are replaced, thus when the user presses the <Del>
2926 key you get the code for the <Del> key, not the raw character
2927 sequence. Examples: >
2928 getchar() == "\<Del>"
2929 getchar() == "\<S-Left>"
2930 < This example redefines "f" to ignore case: >
2931 :nmap f :call FindChar()<CR>
2932 :function FindChar()
2933 : let c = nr2char(getchar())
2934 : while col('.') < col('$') - 1
2935 : normal l
2936 : if getline('.')[col('.') - 1] ==? c
2937 : break
2938 : endif
2939 : endwhile
2940 :endfunction
2942 getcharmod() *getcharmod()*
2943 The result is a Number which is the state of the modifiers for
2944 the last obtained character with getchar() or in another way.
2945 These values are added together:
2946 2 shift
2947 4 control
2948 8 alt (meta)
2949 16 mouse double click
2950 32 mouse triple click
2951 64 mouse quadruple click
2952 128 Macintosh only: command
2953 Only the modifiers that have not been included in the
2954 character itself are obtained. Thus Shift-a results in "A"
2955 with no modifier.
2957 getcmdline() *getcmdline()*
2958 Return the current command-line. Only works when the command
2959 line is being edited, thus requires use of |c_CTRL-\_e| or
2960 |c_CTRL-R_=|.
2961 Example: >
2962 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
2963 < Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
2965 getcmdpos() *getcmdpos()*
2966 Return the position of the cursor in the command line as a
2967 byte count. The first column is 1.
2968 Only works when editing the command line, thus requires use of
2969 |c_CTRL-\_e| or |c_CTRL-R_=|. Returns 0 otherwise.
2970 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
2972 getcmdtype() *getcmdtype()*
2973 Return the current command-line type. Possible return values
2974 are:
2975 : normal Ex command
2976 > debug mode command |debug-mode|
2977 / forward search command
2978 ? backward search command
2979 @ |input()| command
2980 - |:insert| or |:append| command
2981 Only works when editing the command line, thus requires use of
2982 |c_CTRL-\_e| or |c_CTRL-R_=|. Returns an empty string
2983 otherwise.
2984 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
2986 *getcwd()*
2987 getcwd() The result is a String, which is the name of the current
2988 working directory.
2990 getfsize({fname}) *getfsize()*
2991 The result is a Number, which is the size in bytes of the
2992 given file {fname}.
2993 If {fname} is a directory, 0 is returned.
2994 If the file {fname} can't be found, -1 is returned.
2995 If the size of {fname} is too big to fit in a Number then -2
2996 is returned.
2998 getfontname([{name}]) *getfontname()*
2999 Without an argument returns the name of the normal font being
3000 used. Like what is used for the Normal highlight group
3001 |hl-Normal|.
3002 With an argument a check is done whether {name} is a valid
3003 font name. If not then an empty string is returned.
3004 Otherwise the actual font name is returned, or {name} if the
3005 GUI does not support obtaining the real name.
3006 Only works when the GUI is running, thus not in your vimrc or
3007 gvimrc file. Use the |GUIEnter| autocommand to use this
3008 function just after the GUI has started.
3009 Note that the GTK 2 GUI accepts any font name, thus checking
3010 for a valid name does not work.
3012 getfperm({fname}) *getfperm()*
3013 The result is a String, which is the read, write, and execute
3014 permissions of the given file {fname}.
3015 If {fname} does not exist or its directory cannot be read, an
3016 empty string is returned.
3017 The result is of the form "rwxrwxrwx", where each group of
3018 "rwx" flags represent, in turn, the permissions of the owner
3019 of the file, the group the file belongs to, and other users.
3020 If a user does not have a given permission the flag for this
3021 is replaced with the string "-". Example: >
3022 :echo getfperm("/etc/passwd")
3023 < This will hopefully (from a security point of view) display
3024 the string "rw-r--r--" or even "rw-------".
3026 getftime({fname}) *getftime()*
3027 The result is a Number, which is the last modification time of
3028 the given file {fname}. The value is measured as seconds
3029 since 1st Jan 1970, and may be passed to strftime(). See also
3030 |localtime()| and |strftime()|.
3031 If the file {fname} can't be found -1 is returned.
3033 getftype({fname}) *getftype()*
3034 The result is a String, which is a description of the kind of
3035 file of the given file {fname}.
3036 If {fname} does not exist an empty string is returned.
3037 Here is a table over different kinds of files and their
3038 results:
3039 Normal file "file"
3040 Directory "dir"
3041 Symbolic link "link"
3042 Block device "bdev"
3043 Character device "cdev"
3044 Socket "socket"
3045 FIFO "fifo"
3046 All other "other"
3047 Example: >
3048 getftype("/home")
3049 < Note that a type such as "link" will only be returned on
3050 systems that support it. On some systems only "dir" and
3051 "file" are returned.
3053 *getline()*
3054 getline({lnum} [, {end}])
3055 Without {end} the result is a String, which is line {lnum}
3056 from the current buffer. Example: >
3057 getline(1)
3058 < When {lnum} is a String that doesn't start with a
3059 digit, line() is called to translate the String into a Number.
3060 To get the line under the cursor: >
3061 getline(".")
3062 < When {lnum} is smaller than 1 or bigger than the number of
3063 lines in the buffer, an empty string is returned.
3065 When {end} is given the result is a |List| where each item is
3066 a line from the current buffer in the range {lnum} to {end},
3067 including line {end}.
3068 {end} is used in the same way as {lnum}.
3069 Non-existing lines are silently omitted.
3070 When {end} is before {lnum} an empty |List| is returned.
3071 Example: >
3072 :let start = line('.')
3073 :let end = search("^$") - 1
3074 :let lines = getline(start, end)
3076 < To get lines from another buffer see |getbufline()|
3078 getloclist({nr}) *getloclist()*
3079 Returns a list with all the entries in the location list for
3080 window {nr}. When {nr} is zero the current window is used.
3081 For a location list window, the displayed location list is
3082 returned. For an invalid window number {nr}, an empty list is
3083 returned. Otherwise, same as getqflist().
3085 getmatches() *getmatches()*
3086 Returns a |List| with all matches previously defined by
3087 |matchadd()| and the |:match| commands. |getmatches()| is
3088 useful in combination with |setmatches()|, as |setmatches()|
3089 can restore a list of matches saved by |getmatches()|.
3090 Example: >
3091 :echo getmatches()
3092 < [{'group': 'MyGroup1', 'pattern': 'TODO',
3093 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3094 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3095 :let m = getmatches()
3096 :call clearmatches()
3097 :echo getmatches()
3098 < [] >
3099 :call setmatches(m)
3100 :echo getmatches()
3101 < [{'group': 'MyGroup1', 'pattern': 'TODO',
3102 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3103 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3104 :unlet m
3105 <
3107 getqflist() *getqflist()*
3108 Returns a list with all the current quickfix errors. Each
3109 list item is a dictionary with these entries:
3110 bufnr number of buffer that has the file name, use
3111 bufname() to get the name
3112 lnum line number in the buffer (first line is 1)
3113 col column number (first column is 1)
3114 vcol non-zero: "col" is visual column
3115 zero: "col" is byte index
3116 nr error number
3117 pattern search pattern used to locate the error
3118 text description of the error
3119 type type of the error, 'E', '1', etc.
3120 valid non-zero: recognized error message
3122 When there is no error list or it's empty an empty list is
3123 returned. Quickfix list entries with non-existing buffer
3124 number are returned with "bufnr" set to zero.
3126 Useful application: Find pattern matches in multiple files and
3127 do something with them: >
3128 :vimgrep /theword/jg *.c
3129 :for d in getqflist()
3130 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
3131 :endfor
3134 getreg([{regname} [, 1]]) *getreg()*
3135 The result is a String, which is the contents of register
3136 {regname}. Example: >
3137 :let cliptext = getreg('*')
3138 < getreg('=') returns the last evaluated value of the expression
3139 register. (For use in maps.)
3140 getreg('=', 1) returns the expression itself, so that it can
3141 be restored with |setreg()|. For other registers the extra
3142 argument is ignored, thus you can always give it.
3143 If {regname} is not specified, |v:register| is used.
3146 getregtype([{regname}]) *getregtype()*
3147 The result is a String, which is type of register {regname}.
3148 The value will be one of:
3149 "v" for |characterwise| text
3150 "V" for |linewise| text
3151 "<CTRL-V>{width}" for |blockwise-visual| text
3152 0 for an empty or unknown register
3153 <CTRL-V> is one character with value 0x16.
3154 If {regname} is not specified, |v:register| is used.
3156 gettabwinvar({tabnr}, {winnr}, {varname}) *gettabwinvar()*
3157 Get the value of window-local variable {varname} in window
3158 {winnr} in tab page {tabnr}.
3159 When {varname} starts with "&" get the value of a window-local
3160 option.
3161 Tabs are numbered starting with one. For the current tabpage
3162 use |getwinvar()|.
3163 When {winnr} is zero the current window is used.
3164 This also works for a global option, buffer-local option and
3165 window-local option, but it doesn't work for a global variable
3166 or buffer-local variable.
3167 When {varname} is empty a dictionary with all window-local
3168 variables is returned.
3169 Note that {varname} must be the name without "w:".
3170 Examples: >
3171 :let list_is_on = gettabwinvar(1, 2, '&list')
3172 :echo "myvar = " . gettabwinvar(3, 1, 'myvar')
3173 <
3174 *getwinposx()*
3175 getwinposx() The result is a Number, which is the X coordinate in pixels of
3176 the left hand side of the GUI Vim window. The result will be
3177 -1 if the information is not available.
3179 *getwinposy()*
3180 getwinposy() The result is a Number, which is the Y coordinate in pixels of
3181 the top of the GUI Vim window. The result will be -1 if the
3182 information is not available.
3184 getwinvar({winnr}, {varname}) *getwinvar()*
3185 Like |gettabwinvar()| for the current tabpage.
3186 Examples: >
3187 :let list_is_on = getwinvar(2, '&list')
3188 :echo "myvar = " . getwinvar(1, 'myvar')
3189 <
3190 *glob()*
3191 glob({expr}) Expand the file wildcards in {expr}. See |wildcards| for the
3192 use of special characters.
3193 The result is a String.
3194 When there are several matches, they are separated by <NL>
3195 characters.
3196 If the expansion fails, the result is an empty string.
3197 A name for a non-existing file is not included.
3199 For most systems backticks can be used to get files names from
3200 any external command. Example: >
3201 :let tagfiles = glob("`find . -name tags -print`")
3202 :let &tags = substitute(tagfiles, "\n", ",", "g")
3203 < The result of the program inside the backticks should be one
3204 item per line. Spaces inside an item are allowed.
3206 See |expand()| for expanding special Vim variables. See
3207 |system()| for getting the raw output of an external command.
3209 globpath({path}, {expr}) *globpath()*
3210 Perform glob() on all directories in {path} and concatenate
3211 the results. Example: >
3212 :echo globpath(&rtp, "syntax/c.vim")
3213 < {path} is a comma-separated list of directory names. Each
3214 directory name is prepended to {expr} and expanded like with
3215 glob(). A path separator is inserted when needed.
3216 To add a comma inside a directory name escape it with a
3217 backslash. Note that on MS-Windows a directory may have a
3218 trailing backslash, remove it if you put a comma after it.
3219 If the expansion fails for one of the directories, there is no
3220 error message.
3221 The 'wildignore' option applies: Names matching one of the
3222 patterns in 'wildignore' will be skipped.
3224 The "**" item can be used to search in a directory tree.
3225 For example, to find all "README.txt" files in the directories
3226 in 'runtimepath' and below: >
3227 :echo globpath(&rtp, "**/README.txt")
3228 <
3229 *has()*
3230 has({feature}) The result is a Number, which is 1 if the feature {feature} is
3231 supported, zero otherwise. The {feature} argument is a
3232 string. See |feature-list| below.
3233 Also see |exists()|.
3236 has_key({dict}, {key}) *has_key()*
3237 The result is a Number, which is 1 if |Dictionary| {dict} has
3238 an entry with key {key}. Zero otherwise.
3240 haslocaldir() *haslocaldir()*
3241 The result is a Number, which is 1 when the current
3242 window has set a local path via |:lcd|, and 0 otherwise.
3244 hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
3245 The result is a Number, which is 1 if there is a mapping that
3246 contains {what} in somewhere in the rhs (what it is mapped to)
3247 and this mapping exists in one of the modes indicated by
3248 {mode}.
3249 When {abbr} is there and it is non-zero use abbreviations
3250 instead of mappings. Don't forget to specify Insert and/or
3251 Command-line mode.
3252 Both the global mappings and the mappings local to the current
3253 buffer are checked for a match.
3254 If no matching mapping is found 0 is returned.
3255 The following characters are recognized in {mode}:
3256 n Normal mode
3257 v Visual mode
3258 o Operator-pending mode
3259 i Insert mode
3260 l Language-Argument ("r", "f", "t", etc.)
3261 c Command-line mode
3262 When {mode} is omitted, "nvo" is used.
3264 This function is useful to check if a mapping already exists
3265 to a function in a Vim script. Example: >
3266 :if !hasmapto('\ABCdoit')
3267 : map <Leader>d \ABCdoit
3268 :endif
3269 < This installs the mapping to "\ABCdoit" only if there isn't
3270 already a mapping to "\ABCdoit".
3272 histadd({history}, {item}) *histadd()*
3273 Add the String {item} to the history {history} which can be
3274 one of: *hist-names*
3275 "cmd" or ":" command line history
3276 "search" or "/" search pattern history
3277 "expr" or "=" typed expression history
3278 "input" or "@" input line history
3279 If {item} does already exist in the history, it will be
3280 shifted to become the newest entry.
3281 The result is a Number: 1 if the operation was successful,
3282 otherwise 0 is returned.
3284 Example: >
3285 :call histadd("input", strftime("%Y %b %d"))
3286 :let date=input("Enter date: ")
3287 < This function is not available in the |sandbox|.
3289 histdel({history} [, {item}]) *histdel()*
3290 Clear {history}, i.e. delete all its entries. See |hist-names|
3291 for the possible values of {history}.
3293 If the parameter {item} is given as String, this is seen
3294 as regular expression. All entries matching that expression
3295 will be removed from the history (if there are any).
3296 Upper/lowercase must match, unless "\c" is used |/\c|.
3297 If {item} is a Number, it will be interpreted as index, see
3298 |:history-indexing|. The respective entry will be removed
3299 if it exists.
3301 The result is a Number: 1 for a successful operation,
3302 otherwise 0 is returned.
3304 Examples:
3305 Clear expression register history: >
3306 :call histdel("expr")
3307 <
3308 Remove all entries starting with "*" from the search history: >
3309 :call histdel("/", '^\*')
3310 <
3311 The following three are equivalent: >
3312 :call histdel("search", histnr("search"))
3313 :call histdel("search", -1)
3314 :call histdel("search", '^'.histget("search", -1).'$')
3315 <
3316 To delete the last search pattern and use the last-but-one for
3317 the "n" command and 'hlsearch': >
3318 :call histdel("search", -1)
3319 :let @/ = histget("search", -1)
3321 histget({history} [, {index}]) *histget()*
3322 The result is a String, the entry with Number {index} from
3323 {history}. See |hist-names| for the possible values of
3324 {history}, and |:history-indexing| for {index}. If there is
3325 no such entry, an empty String is returned. When {index} is
3326 omitted, the most recent item from the history is used.
3328 Examples:
3329 Redo the second last search from history. >
3330 :execute '/' . histget("search", -2)
3332 < Define an Ex command ":H {num}" that supports re-execution of
3333 the {num}th entry from the output of |:history|. >
3334 :command -nargs=1 H execute histget("cmd", 0+<args>)
3335 <
3336 histnr({history}) *histnr()*
3337 The result is the Number of the current entry in {history}.
3338 See |hist-names| for the possible values of {history}.
3339 If an error occurred, -1 is returned.
3341 Example: >
3342 :let inp_index = histnr("expr")
3343 <
3344 hlexists({name}) *hlexists()*
3345 The result is a Number, which is non-zero if a highlight group
3346 called {name} exists. This is when the group has been
3347 defined in some way. Not necessarily when highlighting has
3348 been defined for it, it may also have been used for a syntax
3349 item.
3350 *highlight_exists()*
3351 Obsolete name: highlight_exists().
3353 *hlID()*
3354 hlID({name}) The result is a Number, which is the ID of the highlight group
3355 with name {name}. When the highlight group doesn't exist,
3356 zero is returned.
3357 This can be used to retrieve information about the highlight
3358 group. For example, to get the background color of the
3359 "Comment" group: >
3360 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
3361 < *highlightID()*
3362 Obsolete name: highlightID().
3364 hostname() *hostname()*
3365 The result is a String, which is the name of the machine on
3366 which Vim is currently running. Machine names greater than
3367 256 characters long are truncated.
3369 iconv({expr}, {from}, {to}) *iconv()*
3370 The result is a String, which is the text {expr} converted
3371 from encoding {from} to encoding {to}.
3372 When the conversion fails an empty string is returned.
3373 The encoding names are whatever the iconv() library function
3374 can accept, see ":!man 3 iconv".
3375 Most conversions require Vim to be compiled with the |+iconv|
3376 feature. Otherwise only UTF-8 to latin1 conversion and back
3377 can be done.
3378 This can be used to display messages with special characters,
3379 no matter what 'encoding' is set to. Write the message in
3380 UTF-8 and use: >
3381 echo iconv(utf8_str, "utf-8", &enc)
3382 < Note that Vim uses UTF-8 for all Unicode encodings, conversion
3383 from/to UCS-2 is automatically changed to use UTF-8. You
3384 cannot use UCS-2 in a string anyway, because of the NUL bytes.
3385 {only available when compiled with the +multi_byte feature}
3387 *indent()*
3388 indent({lnum}) The result is a Number, which is indent of line {lnum} in the
3389 current buffer. The indent is counted in spaces, the value
3390 of 'tabstop' is relevant. {lnum} is used just like in
3391 |getline()|.
3392 When {lnum} is invalid -1 is returned.
3395 index({list}, {expr} [, {start} [, {ic}]]) *index()*
3396 Return the lowest index in |List| {list} where the item has a
3397 value equal to {expr}.
3398 If {start} is given then start looking at the item with index
3399 {start} (may be negative for an item relative to the end).
3400 When {ic} is given and it is non-zero, ignore case. Otherwise
3401 case must match.
3402 -1 is returned when {expr} is not found in {list}.
3403 Example: >
3404 :let idx = index(words, "the")
3405 :if index(numbers, 123) >= 0
3408 input({prompt} [, {text} [, {completion}]]) *input()*
3409 The result is a String, which is whatever the user typed on
3410 the command-line. The parameter is either a prompt string, or
3411 a blank string (for no prompt). A '\n' can be used in the
3412 prompt to start a new line.
3413 The highlighting set with |:echohl| is used for the prompt.
3414 The input is entered just like a command-line, with the same
3415 editing commands and mappings. There is a separate history
3416 for lines typed for input().
3417 Example: >
3418 :if input("Coffee or beer? ") == "beer"
3419 : echo "Cheers!"
3420 :endif
3421 <
3422 If the optional {text} is present and not empty, this is used
3423 for the default reply, as if the user typed this. Example: >
3424 :let color = input("Color? ", "white")
3426 < The optional {completion} argument specifies the type of
3427 completion supported for the input. Without it completion is
3428 not performed. The supported completion types are the same as
3429 that can be supplied to a user-defined command using the
3430 "-complete=" argument. Refer to |:command-completion| for
3431 more information. Example: >
3432 let fname = input("File: ", "", "file")
3433 <
3434 NOTE: This function must not be used in a startup file, for
3435 the versions that only run in GUI mode (e.g., the Win32 GUI).
3436 Note: When input() is called from within a mapping it will
3437 consume remaining characters from that mapping, because a
3438 mapping is handled like the characters were typed.
3439 Use |inputsave()| before input() and |inputrestore()|
3440 after input() to avoid that. Another solution is to avoid
3441 that further characters follow in the mapping, e.g., by using
3442 |:execute| or |:normal|.
3444 Example with a mapping: >
3445 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR>
3446 :function GetFoo()
3447 : call inputsave()
3448 : let g:Foo = input("enter search pattern: ")
3449 : call inputrestore()
3450 :endfunction
3452 inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
3453 Like input(), but when the GUI is running and text dialogs are
3454 supported, a dialog window pops up to input the text.
3455 Example: >
3456 :let n = inputdialog("value for shiftwidth", &sw)
3457 :if n != ""
3458 : let &sw = n
3459 :endif
3460 < When the dialog is cancelled {cancelreturn} is returned. When
3461 omitted an empty string is returned.
3462 Hitting <Enter> works like pressing the OK button. Hitting
3463 <Esc> works like pressing the Cancel button.
3464 NOTE: Command-line completion is not supported.
3466 inputlist({textlist}) *inputlist()*
3467 {textlist} must be a |List| of strings. This |List| is
3468 displayed, one string per line. The user will be prompted to
3469 enter a number, which is returned.
3470 The user can also select an item by clicking on it with the
3471 mouse. For the first string 0 is returned. When clicking
3472 above the first item a negative number is returned. When
3473 clicking on the prompt one more than the length of {textlist}
3474 is returned.
3475 Make sure {textlist} has less then 'lines' entries, otherwise
3476 it won't work. It's a good idea to put the entry number at
3477 the start of the string. And put a prompt in the first item.
3478 Example: >
3479 let color = inputlist(['Select color:', '1. red',
3480 \ '2. green', '3. blue'])
3482 inputrestore() *inputrestore()*
3483 Restore typeahead that was saved with a previous inputsave().
3484 Should be called the same number of times inputsave() is
3485 called. Calling it more often is harmless though.
3486 Returns 1 when there is nothing to restore, 0 otherwise.
3488 inputsave() *inputsave()*
3489 Preserve typeahead (also from mappings) and clear it, so that
3490 a following prompt gets input from the user. Should be
3491 followed by a matching inputrestore() after the prompt. Can
3492 be used several times, in which case there must be just as
3493 many inputrestore() calls.
3494 Returns 1 when out of memory, 0 otherwise.
3496 inputsecret({prompt} [, {text}]) *inputsecret()*
3497 This function acts much like the |input()| function with but
3498 two exceptions:
3499 a) the user's response will be displayed as a sequence of
3500 asterisks ("*") thereby keeping the entry secret, and
3501 b) the user's response will not be recorded on the input
3502 |history| stack.
3503 The result is a String, which is whatever the user actually
3504 typed on the command-line in response to the issued prompt.
3505 NOTE: Command-line completion is not supported.
3507 insert({list}, {item} [, {idx}]) *insert()*
3508 Insert {item} at the start of |List| {list}.
3509 If {idx} is specified insert {item} before the item with index
3510 {idx}. If {idx} is zero it goes before the first item, just
3511 like omitting {idx}. A negative {idx} is also possible, see
3512 |list-index|. -1 inserts just before the last item.
3513 Returns the resulting |List|. Examples: >
3514 :let mylist = insert([2, 3, 5], 1)
3515 :call insert(mylist, 4, -1)
3516 :call insert(mylist, 6, len(mylist))
3517 < The last example can be done simpler with |add()|.
3518 Note that when {item} is a |List| it is inserted as a single
3519 item. Use |extend()| to concatenate |Lists|.
3521 isdirectory({directory}) *isdirectory()*
3522 The result is a Number, which is non-zero when a directory
3523 with the name {directory} exists. If {directory} doesn't
3524 exist, or isn't a directory, the result is FALSE. {directory}
3525 is any expression, which is used as a String.
3527 islocked({expr}) *islocked()* *E786*
3528 The result is a Number, which is non-zero when {expr} is the
3529 name of a locked variable.
3530 {expr} must be the name of a variable, |List| item or
3531 |Dictionary| entry, not the variable itself! Example: >
3532 :let alist = [0, ['a', 'b'], 2, 3]
3533 :lockvar 1 alist
3534 :echo islocked('alist') " 1
3535 :echo islocked('alist[1]') " 0
3537 < When {expr} is a variable that does not exist you get an error
3538 message. Use |exists()| to check for existence.
3540 items({dict}) *items()*
3541 Return a |List| with all the key-value pairs of {dict}. Each
3542 |List| item is a list with two items: the key of a {dict}
3543 entry and the value of this entry. The |List| is in arbitrary
3544 order.
3547 join({list} [, {sep}]) *join()*
3548 Join the items in {list} together into one String.
3549 When {sep} is specified it is put in between the items. If
3550 {sep} is omitted a single space is used.
3551 Note that {sep} is not added at the end. You might want to
3552 add it there too: >
3553 let lines = join(mylist, "\n") . "\n"
3554 < String items are used as-is. |Lists| and |Dictionaries| are
3555 converted into a string like with |string()|.
3556 The opposite function is |split()|.
3558 keys({dict}) *keys()*
3559 Return a |List| with all the keys of {dict}. The |List| is in
3560 arbitrary order.
3562 *len()* *E701*
3563 len({expr}) The result is a Number, which is the length of the argument.
3564 When {expr} is a String or a Number the length in bytes is
3565 used, as with |strlen()|.
3566 When {expr} is a |List| the number of items in the |List| is
3567 returned.
3568 When {expr} is a |Dictionary| the number of entries in the
3569 |Dictionary| is returned.
3570 Otherwise an error is given.
3572 *libcall()* *E364* *E368*
3573 libcall({libname}, {funcname}, {argument})
3574 Call function {funcname} in the run-time library {libname}
3575 with single argument {argument}.
3576 This is useful to call functions in a library that you
3577 especially made to be used with Vim. Since only one argument
3578 is possible, calling standard library functions is rather
3579 limited.
3580 The result is the String returned by the function. If the
3581 function returns NULL, this will appear as an empty string ""
3582 to Vim.
3583 If the function returns a number, use libcallnr()!
3584 If {argument} is a number, it is passed to the function as an
3585 int; if {argument} is a string, it is passed as a
3586 null-terminated string.
3587 This function will fail in |restricted-mode|.
3589 libcall() allows you to write your own 'plug-in' extensions to
3590 Vim without having to recompile the program. It is NOT a
3591 means to call system functions! If you try to do so Vim will
3592 very probably crash.
3594 For Win32, the functions you write must be placed in a DLL
3595 and use the normal C calling convention (NOT Pascal which is
3596 used in Windows System DLLs). The function must take exactly
3597 one parameter, either a character pointer or a long integer,
3598 and must return a character pointer or NULL. The character
3599 pointer returned must point to memory that will remain valid
3600 after the function has returned (e.g. in static data in the
3601 DLL). If it points to allocated memory, that memory will
3602 leak away. Using a static buffer in the function should work,
3603 it's then freed when the DLL is unloaded.
3605 WARNING: If the function returns a non-valid pointer, Vim may
3606 crash! This also happens if the function returns a number,
3607 because Vim thinks it's a pointer.
3608 For Win32 systems, {libname} should be the filename of the DLL
3609 without the ".DLL" suffix. A full path is only required if
3610 the DLL is not in the usual places.
3611 For Unix: When compiling your own plugins, remember that the
3612 object code must be compiled as position-independent ('PIC').
3613 {only in Win32 on some Unix versions, when the |+libcall|
3614 feature is present}
3615 Examples: >
3616 :echo libcall("libc.so", "getenv", "HOME")
3617 <
3618 *libcallnr()*
3619 libcallnr({libname}, {funcname}, {argument})
3620 Just like libcall(), but used for a function that returns an
3621 int instead of a string.
3622 {only in Win32 on some Unix versions, when the |+libcall|
3623 feature is present}
3624 Examples: >
3625 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
3626 :call libcallnr("libc.so", "printf", "Hello World!\n")
3627 :call libcallnr("libc.so", "sleep", 10)
3628 <
3629 *line()*
3630 line({expr}) The result is a Number, which is the line number of the file
3631 position given with {expr}. The accepted positions are:
3632 . the cursor position
3633 $ the last line in the current buffer
3634 'x position of mark x (if the mark is not set, 0 is
3635 returned)
3636 w0 first line visible in current window
3637 w$ last line visible in current window
3638 v In Visual mode: the start of the Visual area (the
3639 cursor is the end). When not in Visual mode
3640 returns the cursor position. Differs from |'<| in
3641 that it's updated right away.
3642 Note that a mark in another file can be used. The line number
3643 then applies to another buffer.
3644 To get the column number use |col()|. To get both use
3645 |getpos()|.
3646 Examples: >
3647 line(".") line number of the cursor
3648 line("'t") line number of mark t
3649 line("'" . marker) line number of mark marker
3650 < *last-position-jump*
3651 This autocommand jumps to the last known position in a file
3652 just after opening it, if the '" mark is set: >
3653 :au BufReadPost * if line("'\"") > 1 && line("'\"") <= line("$") | exe "normal! g'\"" | endif
3655 line2byte({lnum}) *line2byte()*
3656 Return the byte count from the start of the buffer for line
3657 {lnum}. This includes the end-of-line character, depending on
3658 the 'fileformat' option for the current buffer. The first
3659 line returns 1.
3660 This can also be used to get the byte count for the line just
3661 below the last line: >
3662 line2byte(line("$") + 1)
3663 < This is the file size plus one.
3664 When {lnum} is invalid, or the |+byte_offset| feature has been
3665 disabled at compile time, -1 is returned.
3666 Also see |byte2line()|, |go| and |:goto|.
3668 lispindent({lnum}) *lispindent()*
3669 Get the amount of indent for line {lnum} according the lisp
3670 indenting rules, as with 'lisp'.
3671 The indent is counted in spaces, the value of 'tabstop' is
3672 relevant. {lnum} is used just like in |getline()|.
3673 When {lnum} is invalid or Vim was not compiled the
3674 |+lispindent| feature, -1 is returned.
3676 localtime() *localtime()*
3677 Return the current time, measured as seconds since 1st Jan
3678 1970. See also |strftime()| and |getftime()|.
3681 log10({expr}) *log10()*
3682 Return the logarithm of Float {expr} to base 10 as a |Float|.
3683 {expr} must evaluate to a |Float| or a |Number|.
3684 Examples: >
3685 :echo log10(1000)
3686 < 3.0 >
3687 :echo log10(0.01)
3688 < -2.0
3689 {only available when compiled with the |+float| feature}
3691 map({expr}, {string}) *map()*
3692 {expr} must be a |List| or a |Dictionary|.
3693 Replace each item in {expr} with the result of evaluating
3694 {string}.
3695 Inside {string} |v:val| has the value of the current item.
3696 For a |Dictionary| |v:key| has the key of the current item.
3697 Example: >
3698 :call map(mylist, '"> " . v:val . " <"')
3699 < This puts "> " before and " <" after each item in "mylist".
3701 Note that {string} is the result of an expression and is then
3702 used as an expression again. Often it is good to use a
3703 |literal-string| to avoid having to double backslashes. You
3704 still have to double ' quotes
3706 The operation is done in-place. If you want a |List| or
3707 |Dictionary| to remain unmodified make a copy first: >
3708 :let tlist = map(copy(mylist), ' & . "\t"')
3710 < Returns {expr}, the |List| or |Dictionary| that was filtered.
3711 When an error is encountered while evaluating {string} no
3712 further items in {expr} are processed.
3715 maparg({name}[, {mode} [, {abbr}]]) *maparg()*
3716 Return the rhs of mapping {name} in mode {mode}. When there
3717 is no mapping for {name}, an empty String is returned.
3718 {mode} can be one of these strings:
3719 "n" Normal
3720 "v" Visual
3721 "o" Operator-pending
3722 "i" Insert
3723 "c" Cmd-line
3724 "l" langmap |language-mapping|
3725 "" Normal, Visual and Operator-pending
3726 When {mode} is omitted, the modes for "" are used.
3727 When {abbr} is there and it is non-zero use abbreviations
3728 instead of mappings.
3729 The {name} can have special key names, like in the ":map"
3730 command. The returned String has special characters
3731 translated like in the output of the ":map" command listing.
3732 The mappings local to the current buffer are checked first,
3733 then the global mappings.
3734 This function can be used to map a key even when it's already
3735 mapped, and have it do the original mapping too. Sketch: >
3736 exe 'nnoremap <Tab> ==' . maparg('<Tab>', 'n')
3739 mapcheck({name}[, {mode} [, {abbr}]]) *mapcheck()*
3740 Check if there is a mapping that matches with {name} in mode
3741 {mode}. See |maparg()| for {mode} and special names in
3742 {name}.
3743 When {abbr} is there and it is non-zero use abbreviations
3744 instead of mappings.
3745 A match happens with a mapping that starts with {name} and
3746 with a mapping which is equal to the start of {name}.
3748 matches mapping "a" "ab" "abc" ~
3749 mapcheck("a") yes yes yes
3750 mapcheck("abc") yes yes yes
3751 mapcheck("ax") yes no no
3752 mapcheck("b") no no no
3754 The difference with maparg() is that mapcheck() finds a
3755 mapping that matches with {name}, while maparg() only finds a
3756 mapping for {name} exactly.
3757 When there is no mapping that starts with {name}, an empty
3758 String is returned. If there is one, the rhs of that mapping
3759 is returned. If there are several mappings that start with
3760 {name}, the rhs of one of them is returned.
3761 The mappings local to the current buffer are checked first,
3762 then the global mappings.
3763 This function can be used to check if a mapping can be added
3764 without being ambiguous. Example: >
3765 :if mapcheck("_vv") == ""
3766 : map _vv :set guifont=7x13<CR>
3767 :endif
3768 < This avoids adding the "_vv" mapping when there already is a
3769 mapping for "_v" or for "_vvv".
3771 match({expr}, {pat}[, {start}[, {count}]]) *match()*
3772 When {expr} is a |List| then this returns the index of the
3773 first item where {pat} matches. Each item is used as a
3774 String, |Lists| and |Dictionaries| are used as echoed.
3775 Otherwise, {expr} is used as a String. The result is a
3776 Number, which gives the index (byte offset) in {expr} where
3777 {pat} matches.
3778 A match at the first character or |List| item returns zero.
3779 If there is no match -1 is returned.
3780 Example: >
3781 :echo match("testing", "ing") " results in 4
3782 :echo match([1, 'x'], '\a') " results in 1
3783 < See |string-match| for how {pat} is used.
3784 *strpbrk()*
3785 Vim doesn't have a strpbrk() function. But you can do: >
3786 :let sepidx = match(line, '[.,;: \t]')
3787 < *strcasestr()*
3788 Vim doesn't have a strcasestr() function. But you can add
3789 "\c" to the pattern to ignore case: >
3790 :let idx = match(haystack, '\cneedle')
3791 <
3792 If {start} is given, the search starts from byte index
3793 {start} in a String or item {start} in a |List|.
3794 The result, however, is still the index counted from the
3795 first character/item. Example: >
3796 :echo match("testing", "ing", 2)
3797 < result is again "4". >
3798 :echo match("testing", "ing", 4)
3799 < result is again "4". >
3800 :echo match("testing", "t", 2)
3801 < result is "3".
3802 For a String, if {start} > 0 then it is like the string starts
3803 {start} bytes later, thus "^" will match at {start}. Except
3804 when {count} is given, then it's like matches before the
3805 {start} byte are ignored (this is a bit complicated to keep it
3806 backwards compatible).
3807 For a String, if {start} < 0, it will be set to 0. For a list
3808 the index is counted from the end.
3809 If {start} is out of range ({start} > strlen({expr}) for a
3810 String or {start} > len({expr}) for a |List|) -1 is returned.
3812 When {count} is given use the {count}'th match. When a match
3813 is found in a String the search for the next one starts one
3814 character further. Thus this example results in 1: >
3815 echo match("testing", "..", 0, 2)
3816 < In a |List| the search continues in the next item.
3817 Note that when {count} is added the way {start} works changes,
3818 see above.
3820 See |pattern| for the patterns that are accepted.
3821 The 'ignorecase' option is used to set the ignore-caseness of
3822 the pattern. 'smartcase' is NOT used. The matching is always
3823 done like 'magic' is set and 'cpoptions' is empty.
3825 *matchadd()* *E798* *E799* *E801*
3826 matchadd({group}, {pattern}[, {priority}[, {id}]])
3827 Defines a pattern to be highlighted in the current window (a
3828 "match"). It will be highlighted with {group}. Returns an
3829 identification number (ID), which can be used to delete the
3830 match using |matchdelete()|.
3832 The optional {priority} argument assigns a priority to the
3833 match. A match with a high priority will have its
3834 highlighting overrule that of a match with a lower priority.
3835 A priority is specified as an integer (negative numbers are no
3836 exception). If the {priority} argument is not specified, the
3837 default priority is 10. The priority of 'hlsearch' is zero,
3838 hence all matches with a priority greater than zero will
3839 overrule it. Syntax highlighting (see 'syntax') is a separate
3840 mechanism, and regardless of the chosen priority a match will
3841 always overrule syntax highlighting.
3843 The optional {id} argument allows the request for a specific
3844 match ID. If a specified ID is already taken, an error
3845 message will appear and the match will not be added. An ID
3846 is specified as a positive integer (zero excluded). IDs 1, 2
3847 and 3 are reserved for |:match|, |:2match| and |:3match|,
3848 respectively. If the {id} argument is not specified,
3849 |matchadd()| automatically chooses a free ID.
3851 The number of matches is not limited, as it is the case with
3852 the |:match| commands.
3854 Example: >
3855 :highlight MyGroup ctermbg=green guibg=green
3856 :let m = matchadd("MyGroup", "TODO")
3857 < Deletion of the pattern: >
3858 :call matchdelete(m)
3860 < A list of matches defined by |matchadd()| and |:match| are
3861 available from |getmatches()|. All matches can be deleted in
3862 one operation by |clearmatches()|.
3864 matcharg({nr}) *matcharg()*
3865 Selects the {nr} match item, as set with a |:match|,
3866 |:2match| or |:3match| command.
3867 Return a |List| with two elements:
3868 The name of the highlight group used
3869 The pattern used.
3870 When {nr} is not 1, 2 or 3 returns an empty |List|.
3871 When there is no match item set returns ['', ''].
3872 This is useful to save and restore a |:match|.
3873 Highlighting matches using the |:match| commands are limited
3874 to three matches. |matchadd()| does not have this limitation.
3876 matchdelete({id}) *matchdelete()* *E802* *E803*
3877 Deletes a match with ID {id} previously defined by |matchadd()|
3878 or one of the |:match| commands. Returns 0 if successful,
3879 otherwise -1. See example for |matchadd()|. All matches can
3880 be deleted in one operation by |clearmatches()|.
3882 matchend({expr}, {pat}[, {start}[, {count}]]) *matchend()*
3883 Same as match(), but return the index of first character after
3884 the match. Example: >
3885 :echo matchend("testing", "ing")
3886 < results in "7".
3887 *strspn()* *strcspn()*
3888 Vim doesn't have a strspn() or strcspn() function, but you can
3889 do it with matchend(): >
3890 :let span = matchend(line, '[a-zA-Z]')
3891 :let span = matchend(line, '[^a-zA-Z]')
3892 < Except that -1 is returned when there are no matches.
3894 The {start}, if given, has the same meaning as for match(). >
3895 :echo matchend("testing", "ing", 2)
3896 < results in "7". >
3897 :echo matchend("testing", "ing", 5)
3898 < result is "-1".
3899 When {expr} is a |List| the result is equal to match().
3901 matchlist({expr}, {pat}[, {start}[, {count}]]) *matchlist()*
3902 Same as match(), but return a |List|. The first item in the
3903 list is the matched string, same as what matchstr() would
3904 return. Following items are submatches, like "\1", "\2", etc.
3905 in |:substitute|. When an optional submatch didn't match an
3906 empty string is used. Example: >
3907 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
3908 < Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
3909 When there is no match an empty list is returned.
3911 matchstr({expr}, {pat}[, {start}[, {count}]]) *matchstr()*
3912 Same as |match()|, but return the matched string. Example: >
3913 :echo matchstr("testing", "ing")
3914 < results in "ing".
3915 When there is no match "" is returned.
3916 The {start}, if given, has the same meaning as for match(). >
3917 :echo matchstr("testing", "ing", 2)
3918 < results in "ing". >
3919 :echo matchstr("testing", "ing", 5)
3920 < result is "".
3921 When {expr} is a |List| then the matching item is returned.
3922 The type isn't changed, it's not necessarily a String.
3924 *max()*
3925 max({list}) Return the maximum value of all items in {list}.
3926 If {list} is not a list or one of the items in {list} cannot
3927 be used as a Number this results in an error.
3928 An empty |List| results in zero.
3930 *min()*
3931 min({list}) Return the minimum value of all items in {list}.
3932 If {list} is not a list or one of the items in {list} cannot
3933 be used as a Number this results in an error.
3934 An empty |List| results in zero.
3936 *mkdir()* *E739*
3937 mkdir({name} [, {path} [, {prot}]])
3938 Create directory {name}.
3939 If {path} is "p" then intermediate directories are created as
3940 necessary. Otherwise it must be "".
3941 If {prot} is given it is used to set the protection bits of
3942 the new directory. The default is 0755 (rwxr-xr-x: r/w for
3943 the user readable for others). Use 0700 to make it unreadable
3944 for others.
3945 This function is not available in the |sandbox|.
3946 Not available on all systems. To check use: >
3947 :if exists("*mkdir")
3948 <
3949 *mode()*
3950 mode() Return a string that indicates the current mode:
3951 n Normal
3952 v Visual by character
3953 V Visual by line
3954 CTRL-V Visual blockwise
3955 s Select by character
3956 S Select by line
3957 CTRL-S Select blockwise
3958 i Insert
3959 R Replace
3960 c Command-line
3961 r Hit-enter prompt
3962 This is useful in the 'statusline' option. In most other
3963 places it always returns "c" or "n".
3965 nextnonblank({lnum}) *nextnonblank()*
3966 Return the line number of the first line at or below {lnum}
3967 that is not blank. Example: >
3968 if getline(nextnonblank(1)) =~ "Java"
3969 < When {lnum} is invalid or there is no non-blank line at or
3970 below it, zero is returned.
3971 See also |prevnonblank()|.
3973 nr2char({expr}) *nr2char()*
3974 Return a string with a single character, which has the number
3975 value {expr}. Examples: >
3976 nr2char(64) returns "@"
3977 nr2char(32) returns " "
3978 < The current 'encoding' is used. Example for "utf-8": >
3979 nr2char(300) returns I with bow character
3980 < Note that a NUL character in the file is specified with
3981 nr2char(10), because NULs are represented with newline
3982 characters. nr2char(0) is a real NUL and terminates the
3983 string, thus results in an empty string.
3985 *getpid()*
3986 getpid() Return a Number which is the process ID of the Vim process.
3987 On Unix and MS-Windows this is a unique number, until Vim
3988 exits. On MS-DOS it's always zero.
3990 *getpos()*
3991 getpos({expr}) Get the position for {expr}. For possible values of {expr}
3992 see |line()|.
3993 The result is a |List| with four numbers:
3994 [bufnum, lnum, col, off]
3995 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
3996 is the buffer number of the mark.
3997 "lnum" and "col" are the position in the buffer. The first
3998 column is 1.
3999 The "off" number is zero, unless 'virtualedit' is used. Then
4000 it is the offset in screen columns from the start of the
4001 character. E.g., a position within a <Tab> or after the last
4002 character.
4003 This can be used to save and restore the cursor position: >
4004 let save_cursor = getpos(".")
4005 MoveTheCursorAround
4006 call setpos('.', save_cursor)
4007 < Also see |setpos()|.
4009 pathshorten({expr}) *pathshorten()*
4010 Shorten directory names in the path {expr} and return the
4011 result. The tail, the file name, is kept as-is. The other
4012 components in the path are reduced to single letters. Leading
4013 '~' and '.' characters are kept. Example: >
4014 :echo pathshorten('~/.vim/autoload/myfile.vim')
4015 < ~/.v/a/myfile.vim ~
4016 It doesn't matter if the path exists or not.
4018 pow({x}, {y}) *pow()*
4019 Return the power of {x} to the exponent {y} as a |Float|.
4020 {x} and {y} must evaluate to a |Float| or a |Number|.
4021 Examples: >
4022 :echo pow(3, 3)
4023 < 27.0 >
4024 :echo pow(2, 16)
4025 < 65536.0
4026 {only available when compiled with the |+float| feature}
4028 prevnonblank({lnum}) *prevnonblank()*
4029 Return the line number of the first line at or above {lnum}
4030 that is not blank. Example: >
4031 let ind = indent(prevnonblank(v:lnum - 1))
4032 < When {lnum} is invalid or there is no non-blank line at or
4033 above it, zero is returned.
4034 Also see |nextnonblank()|.
4037 printf({fmt}, {expr1} ...) *printf()*
4038 Return a String with {fmt}, where "%" items are replaced by
4039 the formatted form of their respective arguments. Example: >
4040 printf("%4d: E%d %.30s", lnum, errno, msg)
4041 < May result in:
4042 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
4044 Often used items are:
4045 %s string
4046 %6s string right-aligned in 6 bytes
4047 %.9s string truncated to 9 bytes
4048 %c single byte
4049 %d decimal number
4050 %5d decimal number padded with spaces to 5 characters
4051 %x hex number
4052 %04x hex number padded with zeros to at least 4 characters
4053 %X hex number using upper case letters
4054 %o octal number
4055 %f floating point number in the form 123.456
4056 %e floating point number in the form 1.234e3
4057 %E floating point number in the form 1.234E3
4058 %g floating point number, as %f or %e depending on value
4059 %G floating point number, as %f or %E depending on value
4060 %% the % character itself
4062 Conversion specifications start with '%' and end with the
4063 conversion type. All other characters are copied unchanged to
4064 the result.
4066 The "%" starts a conversion specification. The following
4067 arguments appear in sequence:
4069 % [flags] [field-width] [.precision] type
4071 flags
4072 Zero or more of the following flags:
4074 # The value should be converted to an "alternate
4075 form". For c, d, and s conversions, this option
4076 has no effect. For o conversions, the precision
4077 of the number is increased to force the first
4078 character of the output string to a zero (except
4079 if a zero value is printed with an explicit
4080 precision of zero).
4081 For x and X conversions, a non-zero result has
4082 the string "0x" (or "0X" for X conversions)
4083 prepended to it.
4085 0 (zero) Zero padding. For all conversions the converted
4086 value is padded on the left with zeros rather
4087 than blanks. If a precision is given with a
4088 numeric conversion (d, o, x, and X), the 0 flag
4089 is ignored.
4091 - A negative field width flag; the converted value
4092 is to be left adjusted on the field boundary.
4093 The converted value is padded on the right with
4094 blanks, rather than on the left with blanks or
4095 zeros. A - overrides a 0 if both are given.
4097 ' ' (space) A blank should be left before a positive
4098 number produced by a signed conversion (d).
4100 + A sign must always be placed before a number
4101 produced by a signed conversion. A + overrides
4102 a space if both are used.
4104 field-width
4105 An optional decimal digit string specifying a minimum
4106 field width. If the converted value has fewer bytes
4107 than the field width, it will be padded with spaces on
4108 the left (or right, if the left-adjustment flag has
4109 been given) to fill out the field width.
4111 .precision
4112 An optional precision, in the form of a period '.'
4113 followed by an optional digit string. If the digit
4114 string is omitted, the precision is taken as zero.
4115 This gives the minimum number of digits to appear for
4116 d, o, x, and X conversions, or the maximum number of
4117 bytes to be printed from a string for s conversions.
4118 For floating point it is the number of digits after
4119 the decimal point.
4121 type
4122 A character that specifies the type of conversion to
4123 be applied, see below.
4125 A field width or precision, or both, may be indicated by an
4126 asterisk '*' instead of a digit string. In this case, a
4127 Number argument supplies the field width or precision. A
4128 negative field width is treated as a left adjustment flag
4129 followed by a positive field width; a negative precision is
4130 treated as though it were missing. Example: >
4131 :echo printf("%d: %.*s", nr, width, line)
4132 < This limits the length of the text used from "line" to
4133 "width" bytes.
4135 The conversion specifiers and their meanings are:
4137 *printf-d* *printf-o* *printf-x* *printf-X*
4138 doxX The Number argument is converted to signed decimal
4139 (d), unsigned octal (o), or unsigned hexadecimal (x
4140 and X) notation. The letters "abcdef" are used for
4141 x conversions; the letters "ABCDEF" are used for X
4142 conversions.
4143 The precision, if any, gives the minimum number of
4144 digits that must appear; if the converted value
4145 requires fewer digits, it is padded on the left with
4146 zeros.
4147 In no case does a non-existent or small field width
4148 cause truncation of a numeric field; if the result of
4149 a conversion is wider than the field width, the field
4150 is expanded to contain the conversion result.
4152 *printf-c*
4153 c The Number argument is converted to a byte, and the
4154 resulting character is written.
4156 *printf-s*
4157 s The text of the String argument is used. If a
4158 precision is specified, no more bytes than the number
4159 specified are used.
4161 *printf-f* *E807*
4162 f The Float argument is converted into a string of the
4163 form 123.456. The precision specifies the number of
4164 digits after the decimal point. When the precision is
4165 zero the decimal point is omitted. When the precision
4166 is not specified 6 is used. A really big number
4167 (out of range or dividing by zero) results in "inf".
4168 "0.0 / 0.0" results in "nan".
4169 Example: >
4170 echo printf("%.2f", 12.115)
4171 < 12.12
4172 Note that roundoff depends on the system libraries.
4173 Use |round()| when in doubt.
4175 *printf-e* *printf-E*
4176 e E The Float argument is converted into a string of the
4177 form 1.234e+03 or 1.234E+03 when using 'E'. The
4178 precision specifies the number of digits after the
4179 decimal point, like with 'f'.
4181 *printf-g* *printf-G*
4182 g G The Float argument is converted like with 'f' if the
4183 value is between 0.001 (inclusive) and 10000000.0
4184 (exclusive). Otherwise 'e' is used for 'g' and 'E'
4185 for 'G'. When no precision is specified superfluous
4186 zeroes and '+' signs are removed, except for the zero
4187 immediately after the decimal point. Thus 10000000.0
4188 results in 1.0e7.
4190 *printf-%*
4191 % A '%' is written. No argument is converted. The
4192 complete conversion specification is "%%".
4194 Each argument can be Number or String and is converted
4195 automatically to fit the conversion specifier. Any other
4196 argument type results in an error message.
4198 *E766* *E767*
4199 The number of {exprN} arguments must exactly match the number
4200 of "%" items. If there are not sufficient or too many
4201 arguments an error is given. Up to 18 arguments can be used.
4204 pumvisible() *pumvisible()*
4205 Returns non-zero when the popup menu is visible, zero
4206 otherwise. See |ins-completion-menu|.
4207 This can be used to avoid some things that would remove the
4208 popup menu.
4210 *E726* *E727*
4211 range({expr} [, {max} [, {stride}]]) *range()*
4212 Returns a |List| with Numbers:
4213 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
4214 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
4215 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
4216 {max}] (increasing {expr} with {stride} each time, not
4217 producing a value past {max}).
4218 When the maximum is one before the start the result is an
4219 empty list. When the maximum is more than one before the
4220 start this is an error.
4221 Examples: >
4222 range(4) " [0, 1, 2, 3]
4223 range(2, 4) " [2, 3, 4]
4224 range(2, 9, 3) " [2, 5, 8]
4225 range(2, -2, -1) " [2, 1, 0, -1, -2]
4226 range(0) " []
4227 range(2, 0) " error!
4228 <
4229 *readfile()*
4230 readfile({fname} [, {binary} [, {max}]])
4231 Read file {fname} and return a |List|, each line of the file
4232 as an item. Lines broken at NL characters. Macintosh files
4233 separated with CR will result in a single long line (unless a
4234 NL appears somewhere).
4235 When {binary} is equal to "b" binary mode is used:
4236 - When the last line ends in a NL an extra empty list item is
4237 added.
4238 - No CR characters are removed.
4239 Otherwise:
4240 - CR characters that appear before a NL are removed.
4241 - Whether the last line ends in a NL or not does not matter.
4242 All NUL characters are replaced with a NL character.
4243 When {max} is given this specifies the maximum number of lines
4244 to be read. Useful if you only want to check the first ten
4245 lines of a file: >
4246 :for line in readfile(fname, '', 10)
4247 : if line =~ 'Date' | echo line | endif
4248 :endfor
4249 < When {max} is negative -{max} lines from the end of the file
4250 are returned, or as many as there are.
4251 When {max} is zero the result is an empty list.
4252 Note that without {max} the whole file is read into memory.
4253 Also note that there is no recognition of encoding. Read a
4254 file into a buffer if you need to.
4255 When the file can't be opened an error message is given and
4256 the result is an empty list.
4257 Also see |writefile()|.
4259 reltime([{start} [, {end}]]) *reltime()*
4260 Return an item that represents a time value. The format of
4261 the item depends on the system. It can be passed to
4262 |reltimestr()| to convert it to a string.
4263 Without an argument it returns the current time.
4264 With one argument is returns the time passed since the time
4265 specified in the argument.
4266 With two arguments it returns the time passed between {start}
4267 and {end}.
4268 The {start} and {end} arguments must be values returned by
4269 reltime().
4270 {only available when compiled with the +reltime feature}
4272 reltimestr({time}) *reltimestr()*
4273 Return a String that represents the time value of {time}.
4274 This is the number of seconds, a dot and the number of
4275 microseconds. Example: >
4276 let start = reltime()
4277 call MyFunction()
4278 echo reltimestr(reltime(start))
4279 < Note that overhead for the commands will be added to the time.
4280 The accuracy depends on the system.
4281 Leading spaces are used to make the string align nicely. You
4282 can use split() to remove it. >
4283 echo split(reltimestr(reltime(start)))[0]
4284 < Also see |profiling|.
4285 {only available when compiled with the +reltime feature}
4287 *remote_expr()* *E449*
4288 remote_expr({server}, {string} [, {idvar}])
4289 Send the {string} to {server}. The string is sent as an
4290 expression and the result is returned after evaluation.
4291 The result must be a String or a |List|. A |List| is turned
4292 into a String by joining the items with a line break in
4293 between (not at the end), like with join(expr, "\n").
4294 If {idvar} is present, it is taken as the name of a
4295 variable and a {serverid} for later use with
4296 remote_read() is stored there.
4297 See also |clientserver| |RemoteReply|.
4298 This function is not available in the |sandbox|.
4299 {only available when compiled with the |+clientserver| feature}
4300 Note: Any errors will cause a local error message to be issued
4301 and the result will be the empty string.
4302 Examples: >
4303 :echo remote_expr("gvim", "2+2")
4304 :echo remote_expr("gvim1", "b:current_syntax")
4305 <
4307 remote_foreground({server}) *remote_foreground()*
4308 Move the Vim server with the name {server} to the foreground.
4309 This works like: >
4310 remote_expr({server}, "foreground()")
4311 < Except that on Win32 systems the client does the work, to work
4312 around the problem that the OS doesn't always allow the server
4313 to bring itself to the foreground.
4314 Note: This does not restore the window if it was minimized,
4315 like foreground() does.
4316 This function is not available in the |sandbox|.
4317 {only in the Win32, Athena, Motif and GTK GUI versions and the
4318 Win32 console version}
4321 remote_peek({serverid} [, {retvar}]) *remote_peek()*
4322 Returns a positive number if there are available strings
4323 from {serverid}. Copies any reply string into the variable
4324 {retvar} if specified. {retvar} must be a string with the
4325 name of a variable.
4326 Returns zero if none are available.
4327 Returns -1 if something is wrong.
4328 See also |clientserver|.
4329 This function is not available in the |sandbox|.
4330 {only available when compiled with the |+clientserver| feature}
4331 Examples: >
4332 :let repl = ""
4333 :echo "PEEK: ".remote_peek(id, "repl").": ".repl
4335 remote_read({serverid}) *remote_read()*
4336 Return the oldest available reply from {serverid} and consume
4337 it. It blocks until a reply is available.
4338 See also |clientserver|.
4339 This function is not available in the |sandbox|.
4340 {only available when compiled with the |+clientserver| feature}
4341 Example: >
4342 :echo remote_read(id)
4343 <
4344 *remote_send()* *E241*
4345 remote_send({server}, {string} [, {idvar}])
4346 Send the {string} to {server}. The string is sent as input
4347 keys and the function returns immediately. At the Vim server
4348 the keys are not mapped |:map|.
4349 If {idvar} is present, it is taken as the name of a variable
4350 and a {serverid} for later use with remote_read() is stored
4351 there.
4352 See also |clientserver| |RemoteReply|.
4353 This function is not available in the |sandbox|.
4354 {only available when compiled with the |+clientserver| feature}
4355 Note: Any errors will be reported in the server and may mess
4356 up the display.
4357 Examples: >
4358 :echo remote_send("gvim", ":DropAndReply ".file, "serverid").
4359 \ remote_read(serverid)
4361 :autocmd NONE RemoteReply *
4362 \ echo remote_read(expand("<amatch>"))
4363 :echo remote_send("gvim", ":sleep 10 | echo ".
4364 \ 'server2client(expand("<client>"), "HELLO")<CR>')
4365 <
4366 remove({list}, {idx} [, {end}]) *remove()*
4367 Without {end}: Remove the item at {idx} from |List| {list} and
4368 return it.
4369 With {end}: Remove items from {idx} to {end} (inclusive) and
4370 return a list with these items. When {idx} points to the same
4371 item as {end} a list with one item is returned. When {end}
4372 points to an item before {idx} this is an error.
4373 See |list-index| for possible values of {idx} and {end}.
4374 Example: >
4375 :echo "last item: " . remove(mylist, -1)
4376 :call remove(mylist, 0, 9)
4377 remove({dict}, {key})
4378 Remove the entry from {dict} with key {key}. Example: >
4379 :echo "removed " . remove(dict, "one")
4380 < If there is no {key} in {dict} this is an error.
4382 Use |delete()| to remove a file.
4384 rename({from}, {to}) *rename()*
4385 Rename the file by the name {from} to the name {to}. This
4386 should also work to move files across file systems. The
4387 result is a Number, which is 0 if the file was renamed
4388 successfully, and non-zero when the renaming failed.
4389 This function is not available in the |sandbox|.
4391 repeat({expr}, {count}) *repeat()*
4392 Repeat {expr} {count} times and return the concatenated
4393 result. Example: >
4394 :let separator = repeat('-', 80)
4395 < When {count} is zero or negative the result is empty.
4396 When {expr} is a |List| the result is {expr} concatenated
4397 {count} times. Example: >
4398 :let longlist = repeat(['a', 'b'], 3)
4399 < Results in ['a', 'b', 'a', 'b', 'a', 'b'].
4402 resolve({filename}) *resolve()* *E655*
4403 On MS-Windows, when {filename} is a shortcut (a .lnk file),
4404 returns the path the shortcut points to in a simplified form.
4405 On Unix, repeat resolving symbolic links in all path
4406 components of {filename} and return the simplified result.
4407 To cope with link cycles, resolving of symbolic links is
4408 stopped after 100 iterations.
4409 On other systems, return the simplified {filename}.
4410 The simplification step is done as by |simplify()|.
4411 resolve() keeps a leading path component specifying the
4412 current directory (provided the result is still a relative
4413 path name) and also keeps a trailing path separator.
4415 *reverse()*
4416 reverse({list}) Reverse the order of items in {list} in-place. Returns
4417 {list}.
4418 If you want a list to remain unmodified make a copy first: >
4419 :let revlist = reverse(copy(mylist))
4421 round({expr}) *round()*
4422 Round off {expr} to a the nearest integral value and return it
4423 as a |Float|. If {expr} lies halfway between two integral
4424 values, then use the larger one (away from zero).
4425 {expr} must evaluate to a |Float| or a |Number|.
4426 Examples: >
4427 echo round(0.456)
4428 < 0.0 >
4429 echo round(4.5)
4430 < 5.0 >
4431 echo round(-4.5)
4432 < -5.0
4433 {only available when compiled with the |+float| feature}
4436 search({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *search()*
4437 Search for regexp pattern {pattern}. The search starts at the
4438 cursor position (you can use |cursor()| to set it).
4440 {flags} is a String, which can contain these character flags:
4441 'b' search backward instead of forward
4442 'c' accept a match at the cursor position
4443 'e' move to the End of the match
4444 'n' do Not move the cursor
4445 'p' return number of matching sub-pattern (see below)
4446 's' set the ' mark at the previous location of the cursor
4447 'w' wrap around the end of the file
4448 'W' don't wrap around the end of the file
4449 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
4451 If the 's' flag is supplied, the ' mark is set, only if the
4452 cursor is moved. The 's' flag cannot be combined with the 'n'
4453 flag.
4455 'ignorecase', 'smartcase' and 'magic' are used.
4457 When the {stopline} argument is given then the search stops
4458 after searching this line. This is useful to restrict the
4459 search to a range of lines. Examples: >
4460 let match = search('(', 'b', line("w0"))
4461 let end = search('END', '', line("w$"))
4462 < When {stopline} is used and it is not zero this also implies
4463 that the search does not wrap around the end of the file.
4464 A zero value is equal to not giving the argument.
4466 When the {timeout} argument is given the search stops when
4467 more than this many milli seconds have passed. Thus when
4468 {timeout} is 500 the search stops after half a second.
4469 The value must not be negative. A zero value is like not
4470 giving the argument.
4471 {only available when compiled with the +reltime feature}
4473 If there is no match a 0 is returned and the cursor doesn't
4474 move. No error message is given.
4475 When a match has been found its line number is returned.
4476 *search()-sub-match*
4477 With the 'p' flag the returned value is one more than the
4478 first sub-match in \(\). One if none of them matched but the
4479 whole pattern did match.
4480 To get the column number too use |searchpos()|.
4482 The cursor will be positioned at the match, unless the 'n'
4483 flag is used.
4485 Example (goes over all files in the argument list): >
4486 :let n = 1
4487 :while n <= argc() " loop over all files in arglist
4488 : exe "argument " . n
4489 : " start at the last char in the file and wrap for the
4490 : " first search to find match at start of file
4491 : normal G$
4492 : let flags = "w"
4493 : while search("foo", flags) > 0
4494 : s/foo/bar/g
4495 : let flags = "W"
4496 : endwhile
4497 : update " write the file if modified
4498 : let n = n + 1
4499 :endwhile
4500 <
4501 Example for using some flags: >
4502 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
4503 < This will search for the keywords "if", "else", and "endif"
4504 under or after the cursor. Because of the 'p' flag, it
4505 returns 1, 2, or 3 depending on which keyword is found, or 0
4506 if the search fails. With the cursor on the first word of the
4507 line:
4508 if (foo == 0) | let foo = foo + 1 | endif ~
4509 the function returns 1. Without the 'c' flag, the function
4510 finds the "endif" and returns 3. The same thing happens
4511 without the 'e' flag if the cursor is on the "f" of "if".
4512 The 'n' flag tells the function not to move the cursor.
4515 searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
4516 Search for the declaration of {name}.
4518 With a non-zero {global} argument it works like |gD|, find
4519 first match in the file. Otherwise it works like |gd|, find
4520 first match in the function.
4522 With a non-zero {thisblock} argument matches in a {} block
4523 that ends before the cursor position are ignored. Avoids
4524 finding variable declarations only valid in another scope.
4526 Moves the cursor to the found match.
4527 Returns zero for success, non-zero for failure.
4528 Example: >
4529 if searchdecl('myvar') == 0
4530 echo getline('.')
4531 endif
4532 <
4533 *searchpair()*
4534 searchpair({start}, {middle}, {end} [, {flags} [, {skip}
4535 [, {stopline} [, {timeout}]]]])
4536 Search for the match of a nested start-end pair. This can be
4537 used to find the "endif" that matches an "if", while other
4538 if/endif pairs in between are ignored.
4539 The search starts at the cursor. The default is to search
4540 forward, include 'b' in {flags} to search backward.
4541 If a match is found, the cursor is positioned at it and the
4542 line number is returned. If no match is found 0 or -1 is
4543 returned and the cursor doesn't move. No error message is
4544 given.
4546 {start}, {middle} and {end} are patterns, see |pattern|. They
4547 must not contain \( \) pairs. Use of \%( \) is allowed. When
4548 {middle} is not empty, it is found when searching from either
4549 direction, but only when not in a nested start-end pair. A
4550 typical use is: >
4551 searchpair('\<if\>', '\<else\>', '\<endif\>')
4552 < By leaving {middle} empty the "else" is skipped.
4554 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
4555 |search()|. Additionally:
4556 'r' Repeat until no more matches found; will find the
4557 outer pair. Implies the 'W' flag.
4558 'm' Return number of matches instead of line number with
4559 the match; will be > 1 when 'r' is used.
4560 Note: it's nearly always a good idea to use the 'W' flag, to
4561 avoid wrapping around the end of the file.
4563 When a match for {start}, {middle} or {end} is found, the
4564 {skip} expression is evaluated with the cursor positioned on
4565 the start of the match. It should return non-zero if this
4566 match is to be skipped. E.g., because it is inside a comment
4567 or a string.
4568 When {skip} is omitted or empty, every match is accepted.
4569 When evaluating {skip} causes an error the search is aborted
4570 and -1 returned.
4572 For {stopline} and {timeout} see |search()|.
4574 The value of 'ignorecase' is used. 'magic' is ignored, the
4575 patterns are used like it's on.
4577 The search starts exactly at the cursor. A match with
4578 {start}, {middle} or {end} at the next character, in the
4579 direction of searching, is the first one found. Example: >
4580 if 1
4581 if 2
4582 endif 2
4583 endif 1
4584 < When starting at the "if 2", with the cursor on the "i", and
4585 searching forwards, the "endif 2" is found. When starting on
4586 the character just before the "if 2", the "endif 1" will be
4587 found. That's because the "if 2" will be found first, and
4588 then this is considered to be a nested if/endif from "if 2" to
4589 "endif 2".
4590 When searching backwards and {end} is more than one character,
4591 it may be useful to put "\zs" at the end of the pattern, so
4592 that when the cursor is inside a match with the end it finds
4593 the matching start.
4595 Example, to find the "endif" command in a Vim script: >
4597 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
4598 \ 'getline(".") =~ "^\\s*\""')
4600 < The cursor must be at or after the "if" for which a match is
4601 to be found. Note that single-quote strings are used to avoid
4602 having to double the backslashes. The skip expression only
4603 catches comments at the start of a line, not after a command.
4604 Also, a word "en" or "if" halfway a line is considered a
4605 match.
4606 Another example, to search for the matching "{" of a "}": >
4608 :echo searchpair('{', '', '}', 'bW')
4610 < This works when the cursor is at or before the "}" for which a
4611 match is to be found. To reject matches that syntax
4612 highlighting recognized as strings: >
4614 :echo searchpair('{', '', '}', 'bW',
4615 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
4616 <
4617 *searchpairpos()*
4618 searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
4619 [, {stopline} [, {timeout}]]]])
4620 Same as searchpair(), but returns a |List| with the line and
4621 column position of the match. The first element of the |List|
4622 is the line number and the second element is the byte index of
4623 the column position of the match. If no match is found,
4624 returns [0, 0].
4625 >
4626 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
4627 <
4628 See |match-parens| for a bigger and more useful example.
4630 searchpos({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *searchpos()*
4631 Same as |search()|, but returns a |List| with the line and
4632 column position of the match. The first element of the |List|
4633 is the line number and the second element is the byte index of
4634 the column position of the match. If no match is found,
4635 returns [0, 0].
4636 Example: >
4637 :let [lnum, col] = searchpos('mypattern', 'n')
4639 < When the 'p' flag is given then there is an extra item with
4640 the sub-pattern match number |search()-sub-match|. Example: >
4641 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
4642 < In this example "submatch" is 2 when a lowercase letter is
4643 found |/\l|, 3 when an uppercase letter is found |/\u|.
4645 server2client( {clientid}, {string}) *server2client()*
4646 Send a reply string to {clientid}. The most recent {clientid}
4647 that sent a string can be retrieved with expand("<client>").
4648 {only available when compiled with the |+clientserver| feature}
4649 Note:
4650 This id has to be stored before the next command can be
4651 received. I.e. before returning from the received command and
4652 before calling any commands that waits for input.
4653 See also |clientserver|.
4654 Example: >
4655 :echo server2client(expand("<client>"), "HELLO")
4656 <
4657 serverlist() *serverlist()*
4658 Return a list of available server names, one per line.
4659 When there are no servers or the information is not available
4660 an empty string is returned. See also |clientserver|.
4661 {only available when compiled with the |+clientserver| feature}
4662 Example: >
4663 :echo serverlist()
4664 <
4665 setbufvar({expr}, {varname}, {val}) *setbufvar()*
4666 Set option or local variable {varname} in buffer {expr} to
4667 {val}.
4668 This also works for a global or local window option, but it
4669 doesn't work for a global or local window variable.
4670 For a local window option the global value is unchanged.
4671 For the use of {expr}, see |bufname()| above.
4672 Note that the variable name without "b:" must be used.
4673 Examples: >
4674 :call setbufvar(1, "&mod", 1)
4675 :call setbufvar("todo", "myvar", "foobar")
4676 < This function is not available in the |sandbox|.
4678 setcmdpos({pos}) *setcmdpos()*
4679 Set the cursor position in the command line to byte position
4680 {pos}. The first position is 1.
4681 Use |getcmdpos()| to obtain the current position.
4682 Only works while editing the command line, thus you must use
4683 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
4684 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
4685 set after the command line is set to the expression. For
4686 |c_CTRL-R_=| it is set after evaluating the expression but
4687 before inserting the resulting text.
4688 When the number is too big the cursor is put at the end of the
4689 line. A number smaller than one has undefined results.
4690 Returns 0 when successful, 1 when not editing the command
4691 line.
4693 setline({lnum}, {text}) *setline()*
4694 Set line {lnum} of the current buffer to {text}.
4695 {lnum} is used like with |getline()|.
4696 When {lnum} is just below the last line the {text} will be
4697 added as a new line.
4698 If this succeeds, 0 is returned. If this fails (most likely
4699 because {lnum} is invalid) 1 is returned. Example: >
4700 :call setline(5, strftime("%c"))
4701 < When {text} is a |List| then line {lnum} and following lines
4702 will be set to the items in the list. Example: >
4703 :call setline(5, ['aaa', 'bbb', 'ccc'])
4704 < This is equivalent to: >
4705 :for [n, l] in [[5, 6, 7], ['aaa', 'bbb', 'ccc']]
4706 : call setline(n, l)
4707 :endfor
4708 < Note: The '[ and '] marks are not set.
4710 setloclist({nr}, {list} [, {action}]) *setloclist()*
4711 Create or replace or add to the location list for window {nr}.
4712 When {nr} is zero the current window is used. For a location
4713 list window, the displayed location list is modified. For an
4714 invalid window number {nr}, -1 is returned.
4715 Otherwise, same as |setqflist()|.
4716 Also see |location-list|.
4718 setmatches({list}) *setmatches()*
4719 Restores a list of matches saved by |getmatches()|. Returns 0
4720 if successful, otherwise -1. All current matches are cleared
4721 before the list is restored. See example for |getmatches()|.
4723 *setpos()*
4724 setpos({expr}, {list})
4725 Set the position for {expr}. Possible values:
4726 . the cursor
4727 'x mark x
4729 {list} must be a |List| with four numbers:
4730 [bufnum, lnum, col, off]
4732 "bufnum" is the buffer number. Zero can be used for the
4733 current buffer. Setting the cursor is only possible for
4734 the current buffer. To set a mark in another buffer you can
4735 use the |bufnr()| function to turn a file name into a buffer
4736 number.
4737 Does not change the jumplist.
4739 "lnum" and "col" are the position in the buffer. The first
4740 column is 1. Use a zero "lnum" to delete a mark.
4742 The "off" number is only used when 'virtualedit' is set. Then
4743 it is the offset in screen columns from the start of the
4744 character. E.g., a position within a <Tab> or after the last
4745 character.
4747 Returns 0 when the position could be set, -1 otherwise.
4748 An error message is given if {expr} is invalid.
4750 Also see |getpos()|
4752 This does not restore the preferred column for moving
4753 vertically. See |winrestview()| for that.
4756 setqflist({list} [, {action}]) *setqflist()*
4757 Create or replace or add to the quickfix list using the items
4758 in {list}. Each item in {list} is a dictionary.
4759 Non-dictionary items in {list} are ignored. Each dictionary
4760 item can contain the following entries:
4762 bufnr buffer number; must be the number of a valid
4763 buffer
4764 filename name of a file; only used when "bufnr" is not
4765 present or it is invalid.
4766 lnum line number in the file
4767 pattern search pattern used to locate the error
4768 col column number
4769 vcol when non-zero: "col" is visual column
4770 when zero: "col" is byte index
4771 nr error number
4772 text description of the error
4773 type single-character error type, 'E', 'W', etc.
4775 The "col", "vcol", "nr", "type" and "text" entries are
4776 optional. Either "lnum" or "pattern" entry can be used to
4777 locate a matching error line.
4778 If the "filename" and "bufnr" entries are not present or
4779 neither the "lnum" or "pattern" entries are present, then the
4780 item will not be handled as an error line.
4781 If both "pattern" and "lnum" are present then "pattern" will
4782 be used.
4783 Note that the list is not exactly the same as what
4784 |getqflist()| returns.
4786 If {action} is set to 'a', then the items from {list} are
4787 added to the existing quickfix list. If there is no existing
4788 list, then a new list is created. If {action} is set to 'r',
4789 then the items from the current quickfix list are replaced
4790 with the items from {list}. If {action} is not present or is
4791 set to ' ', then a new list is created.
4793 Returns zero for success, -1 for failure.
4795 This function can be used to create a quickfix list
4796 independent of the 'errorformat' setting. Use a command like
4797 ":cc 1" to jump to the first position.
4800 *setreg()*
4801 setreg({regname}, {value} [,{options}])
4802 Set the register {regname} to {value}.
4803 If {options} contains "a" or {regname} is upper case,
4804 then the value is appended.
4805 {options} can also contains a register type specification:
4806 "c" or "v" |characterwise| mode
4807 "l" or "V" |linewise| mode
4808 "b" or "<CTRL-V>" |blockwise-visual| mode
4809 If a number immediately follows "b" or "<CTRL-V>" then this is
4810 used as the width of the selection - if it is not specified
4811 then the width of the block is set to the number of characters
4812 in the longest line (counting a <Tab> as 1 character).
4814 If {options} contains no register settings, then the default
4815 is to use character mode unless {value} ends in a <NL>.
4816 Setting the '=' register is not possible.
4817 Returns zero for success, non-zero for failure.
4819 Examples: >
4820 :call setreg(v:register, @*)
4821 :call setreg('*', @%, 'ac')
4822 :call setreg('a', "1\n2\n3", 'b5')
4824 < This example shows using the functions to save and restore a
4825 register. >
4826 :let var_a = getreg('a', 1)
4827 :let var_amode = getregtype('a')
4828 ....
4829 :call setreg('a', var_a, var_amode)
4831 < You can also change the type of a register by appending
4832 nothing: >
4833 :call setreg('a', '', 'al')
4835 settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
4836 Set option or local variable {varname} in window {winnr} to
4837 {val}.
4838 Tabs are numbered starting with one. For the current tabpage
4839 use |setwinvar()|.
4840 When {winnr} is zero the current window is used.
4841 This also works for a global or local buffer option, but it
4842 doesn't work for a global or local buffer variable.
4843 For a local buffer option the global value is unchanged.
4844 Note that the variable name without "w:" must be used.
4845 Vim briefly goes to the tab page {tabnr}, this may trigger
4846 TabLeave and TabEnter autocommands.
4847 Examples: >
4848 :call settabwinvar(1, 1, "&list", 0)
4849 :call settabwinvar(3, 2, "myvar", "foobar")
4850 < This function is not available in the |sandbox|.
4852 setwinvar({nr}, {varname}, {val}) *setwinvar()*
4853 Like |settabwinvar()| for the current tab page.
4854 Examples: >
4855 :call setwinvar(1, "&list", 0)
4856 :call setwinvar(2, "myvar", "foobar")
4858 shellescape({string}) *shellescape()*
4859 Escape {string} for use as shell command argument.
4860 On MS-Windows and MS-DOS, when 'shellslash' is not set, it
4861 will enclose {string} double quotes and double all double
4862 quotes within {string}.
4863 For other systems, it will enclose {string} in single quotes
4864 and replace all "'" with "'\''".
4865 Example: >
4866 :echo shellescape('c:\program files\vim')
4867 < results in:
4868 "c:\program files\vim" ~
4869 Example usage: >
4870 :call system("chmod +x -- " . shellescape(expand("%")))
4873 simplify({filename}) *simplify()*
4874 Simplify the file name as much as possible without changing
4875 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
4876 Unix) are not resolved. If the first path component in
4877 {filename} designates the current directory, this will be
4878 valid for the result as well. A trailing path separator is
4879 not removed either.
4880 Example: >
4881 simplify("./dir/.././/file/") == "./file/"
4882 < Note: The combination "dir/.." is only removed if "dir" is
4883 a searchable directory or does not exist. On Unix, it is also
4884 removed when "dir" is a symbolic link within the same
4885 directory. In order to resolve all the involved symbolic
4886 links before simplifying the path name, use |resolve()|.
4889 sort({list} [, {func}]) *sort()* *E702*
4890 Sort the items in {list} in-place. Returns {list}. If you
4891 want a list to remain unmodified make a copy first: >
4892 :let sortedlist = sort(copy(mylist))
4893 < Uses the string representation of each item to sort on.
4894 Numbers sort after Strings, |Lists| after Numbers.
4895 For sorting text in the current buffer use |:sort|.
4896 When {func} is given and it is one then case is ignored.
4897 When {func} is a |Funcref| or a function name, this function
4898 is called to compare items. The function is invoked with two
4899 items as argument and must return zero if they are equal, 1 if
4900 the first one sorts after the second one, -1 if the first one
4901 sorts before the second one. Example: >
4902 func MyCompare(i1, i2)
4903 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
4904 endfunc
4905 let sortedlist = sort(mylist, "MyCompare")
4906 <
4908 *soundfold()*
4909 soundfold({word})
4910 Return the sound-folded equivalent of {word}. Uses the first
4911 language in 'spelllang' for the current window that supports
4912 soundfolding. 'spell' must be set. When no sound folding is
4913 possible the {word} is returned unmodified.
4914 This can be used for making spelling suggestions. Note that
4915 the method can be quite slow.
4917 *spellbadword()*
4918 spellbadword([{sentence}])
4919 Without argument: The result is the badly spelled word under
4920 or after the cursor. The cursor is moved to the start of the
4921 bad word. When no bad word is found in the cursor line the
4922 result is an empty string and the cursor doesn't move.
4924 With argument: The result is the first word in {sentence} that
4925 is badly spelled. If there are no spelling mistakes the
4926 result is an empty string.
4928 The return value is a list with two items:
4929 - The badly spelled word or an empty string.
4930 - The type of the spelling error:
4931 "bad" spelling mistake
4932 "rare" rare word
4933 "local" word only valid in another region
4934 "caps" word should start with Capital
4935 Example: >
4936 echo spellbadword("the quik brown fox")
4937 < ['quik', 'bad'] ~
4939 The spelling information for the current window is used. The
4940 'spell' option must be set and the value of 'spelllang' is
4941 used.
4943 *spellsuggest()*
4944 spellsuggest({word} [, {max} [, {capital}]])
4945 Return a |List| with spelling suggestions to replace {word}.
4946 When {max} is given up to this number of suggestions are
4947 returned. Otherwise up to 25 suggestions are returned.
4949 When the {capital} argument is given and it's non-zero only
4950 suggestions with a leading capital will be given. Use this
4951 after a match with 'spellcapcheck'.
4953 {word} can be a badly spelled word followed by other text.
4954 This allows for joining two words that were split. The
4955 suggestions also include the following text, thus you can
4956 replace a line.
4958 {word} may also be a good word. Similar words will then be
4959 returned. {word} itself is not included in the suggestions,
4960 although it may appear capitalized.
4962 The spelling information for the current window is used. The
4963 'spell' option must be set and the values of 'spelllang' and
4964 'spellsuggest' are used.
4967 split({expr} [, {pattern} [, {keepempty}]]) *split()*
4968 Make a |List| out of {expr}. When {pattern} is omitted or
4969 empty each white-separated sequence of characters becomes an
4970 item.
4971 Otherwise the string is split where {pattern} matches,
4972 removing the matched characters.
4973 When the first or last item is empty it is omitted, unless the
4974 {keepempty} argument is given and it's non-zero.
4975 Other empty items are kept when {pattern} matches at least one
4976 character or when {keepempty} is non-zero.
4977 Example: >
4978 :let words = split(getline('.'), '\W\+')
4979 < To split a string in individual characters: >
4980 :for c in split(mystring, '\zs')
4981 < If you want to keep the separator you can also use '\zs': >
4982 :echo split('abc:def:ghi', ':\zs')
4983 < ['abc:', 'def:', 'ghi'] ~
4984 Splitting a table where the first element can be empty: >
4985 :let items = split(line, ':', 1)
4986 < The opposite function is |join()|.
4989 sqrt({expr}) *sqrt()*
4990 Return the non-negative square root of Float {expr} as a
4991 |Float|.
4992 {expr} must evaluate to a |Float| or a |Number|. When {expr}
4993 is negative the result is NaN (Not a Number).
4994 Examples: >
4995 :echo sqrt(100)
4996 < 10.0 >
4997 :echo sqrt(-4.01)
4998 < nan
4999 {only available when compiled with the |+float| feature}
5001 str2nr( {expr} [, {base}]) *str2nr()*
5002 Convert string {expr} to a number.
5003 {base} is the conversion base, it can be 8, 10 or 16.
5004 When {base} is omitted base 10 is used. This also means that
5005 a leading zero doesn't cause octal conversion to be used, as
5006 with the default String to Number conversion.
5007 When {base} is 16 a leading "0x" or "0X" is ignored. With a
5008 different base the result will be zero.
5009 Text after the number is silently ignored.
5012 str2float( {expr}) *str2float()*
5013 Convert string {expr} to a Float. This mostly works the same
5014 as when using a floating point number in an expression, see
5015 |floating-point-format|. But it's a bit more permissive.
5016 E.g., "1e40" is accepted, while in an expression you need to
5017 write "1.0e40".
5018 Text after the number is silently ignored.
5019 The decimal point is always '.', no matter what the locale is
5020 set to. A comma ends the number: "12,345.67" is converted to
5021 12.0. You can strip out thousands separators with
5022 |substitute()|: >
5023 let f = str2float(substitute(text, ',', '', 'g'))
5024 < {only available when compiled with the |+float| feature}
5027 strftime({format} [, {time}]) *strftime()*
5028 The result is a String, which is a formatted date and time, as
5029 specified by the {format} string. The given {time} is used,
5030 or the current time if no time is given. The accepted
5031 {format} depends on your system, thus this is not portable!
5032 See the manual page of the C function strftime() for the
5033 format. The maximum length of the result is 80 characters.
5034 See also |localtime()| and |getftime()|.
5035 The language can be changed with the |:language| command.
5036 Examples: >
5037 :echo strftime("%c") Sun Apr 27 11:49:23 1997
5038 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
5039 :echo strftime("%y%m%d %T") 970427 11:53:55
5040 :echo strftime("%H:%M") 11:55
5041 :echo strftime("%c", getftime("file.c"))
5042 Show mod time of file.c.
5043 < Not available on all systems. To check use: >
5044 :if exists("*strftime")
5046 stridx({haystack}, {needle} [, {start}]) *stridx()*
5047 The result is a Number, which gives the byte index in
5048 {haystack} of the first occurrence of the String {needle}.
5049 If {start} is specified, the search starts at index {start}.
5050 This can be used to find a second match: >
5051 :let comma1 = stridx(line, ",")
5052 :let comma2 = stridx(line, ",", comma1 + 1)
5053 < The search is done case-sensitive.
5054 For pattern searches use |match()|.
5055 -1 is returned if the {needle} does not occur in {haystack}.
5056 See also |strridx()|.
5057 Examples: >
5058 :echo stridx("An Example", "Example") 3
5059 :echo stridx("Starting point", "Start") 0
5060 :echo stridx("Starting point", "start") -1
5061 < *strstr()* *strchr()*
5062 stridx() works similar to the C function strstr(). When used
5063 with a single character it works similar to strchr().
5065 *string()*
5066 string({expr}) Return {expr} converted to a String. If {expr} is a Number,
5067 Float, String or a composition of them, then the result can be
5068 parsed back with |eval()|.
5069 {expr} type result ~
5070 String 'string'
5071 Number 123
5072 Float 123.456789 or 1.234567e8
5073 Funcref function('name')
5074 List [item, item]
5075 Dictionary {key: value, key: value}
5076 Note that in String values the ' character is doubled.
5077 Also see |strtrans()|.
5079 *strlen()*
5080 strlen({expr}) The result is a Number, which is the length of the String
5081 {expr} in bytes.
5082 If you want to count the number of multi-byte characters (not
5083 counting composing characters) use something like this: >
5085 :let len = strlen(substitute(str, ".", "x", "g"))
5086 <
5087 If the argument is a Number it is first converted to a String.
5088 For other types an error is given.
5089 Also see |len()|.
5091 strpart({src}, {start}[, {len}]) *strpart()*
5092 The result is a String, which is part of {src}, starting from
5093 byte {start}, with the byte length {len}.
5094 When non-existing bytes are included, this doesn't result in
5095 an error, the bytes are simply omitted.
5096 If {len} is missing, the copy continues from {start} till the
5097 end of the {src}. >
5098 strpart("abcdefg", 3, 2) == "de"
5099 strpart("abcdefg", -2, 4) == "ab"
5100 strpart("abcdefg", 5, 4) == "fg"
5101 strpart("abcdefg", 3) == "defg"
5102 < Note: To get the first character, {start} must be 0. For
5103 example, to get three bytes under and after the cursor: >
5104 strpart(getline("."), col(".") - 1, 3)
5105 <
5106 strridx({haystack}, {needle} [, {start}]) *strridx()*
5107 The result is a Number, which gives the byte index in
5108 {haystack} of the last occurrence of the String {needle}.
5109 When {start} is specified, matches beyond this index are
5110 ignored. This can be used to find a match before a previous
5111 match: >
5112 :let lastcomma = strridx(line, ",")
5113 :let comma2 = strridx(line, ",", lastcomma - 1)
5114 < The search is done case-sensitive.
5115 For pattern searches use |match()|.
5116 -1 is returned if the {needle} does not occur in {haystack}.
5117 If the {needle} is empty the length of {haystack} is returned.
5118 See also |stridx()|. Examples: >
5119 :echo strridx("an angry armadillo", "an") 3
5120 < *strrchr()*
5121 When used with a single character it works similar to the C
5122 function strrchr().
5124 strtrans({expr}) *strtrans()*
5125 The result is a String, which is {expr} with all unprintable
5126 characters translated into printable characters |'isprint'|.
5127 Like they are shown in a window. Example: >
5128 echo strtrans(@a)
5129 < This displays a newline in register a as "^@" instead of
5130 starting a new line.
5132 submatch({nr}) *submatch()*
5133 Only for an expression in a |:substitute| command. Returns
5134 the {nr}'th submatch of the matched text. When {nr} is 0
5135 the whole matched text is returned.
5136 Example: >
5137 :s/\d\+/\=submatch(0) + 1/
5138 < This finds the first number in the line and adds one to it.
5139 A line break is included as a newline character.
5141 substitute({expr}, {pat}, {sub}, {flags}) *substitute()*
5142 The result is a String, which is a copy of {expr}, in which
5143 the first match of {pat} is replaced with {sub}. This works
5144 like the ":substitute" command (without any flags). But the
5145 matching with {pat} is always done like the 'magic' option is
5146 set and 'cpoptions' is empty (to make scripts portable).
5147 'ignorecase' is still relevant. 'smartcase' is not used.
5148 See |string-match| for how {pat} is used.
5149 And a "~" in {sub} is not replaced with the previous {sub}.
5150 Note that some codes in {sub} have a special meaning
5151 |sub-replace-special|. For example, to replace something with
5152 "\n" (two characters), use "\\\\n" or '\\n'.
5153 When {pat} does not match in {expr}, {expr} is returned
5154 unmodified.
5155 When {flags} is "g", all matches of {pat} in {expr} are
5156 replaced. Otherwise {flags} should be "".
5157 Example: >
5158 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
5159 < This removes the last component of the 'path' option. >
5160 :echo substitute("testing", ".*", "\\U\\0", "")
5161 < results in "TESTING".
5163 synID({lnum}, {col}, {trans}) *synID()*
5164 The result is a Number, which is the syntax ID at the position
5165 {lnum} and {col} in the current window.
5166 The syntax ID can be used with |synIDattr()| and
5167 |synIDtrans()| to obtain syntax information about text.
5169 {col} is 1 for the leftmost column, {lnum} is 1 for the first
5170 line. 'synmaxcol' applies, in a longer line zero is returned.
5172 When {trans} is non-zero, transparent items are reduced to the
5173 item that they reveal. This is useful when wanting to know
5174 the effective color. When {trans} is zero, the transparent
5175 item is returned. This is useful when wanting to know which
5176 syntax item is effective (e.g. inside parens).
5177 Warning: This function can be very slow. Best speed is
5178 obtained by going through the file in forward direction.
5180 Example (echoes the name of the syntax item under the cursor): >
5181 :echo synIDattr(synID(line("."), col("."), 1), "name")
5182 <
5183 synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
5184 The result is a String, which is the {what} attribute of
5185 syntax ID {synID}. This can be used to obtain information
5186 about a syntax item.
5187 {mode} can be "gui", "cterm" or "term", to get the attributes
5188 for that mode. When {mode} is omitted, or an invalid value is
5189 used, the attributes for the currently active highlighting are
5190 used (GUI, cterm or term).
5191 Use synIDtrans() to follow linked highlight groups.
5192 {what} result
5193 "name" the name of the syntax item
5194 "fg" foreground color (GUI: color name used to set
5195 the color, cterm: color number as a string,
5196 term: empty string)
5197 "bg" background color (like "fg")
5198 "fg#" like "fg", but for the GUI and the GUI is
5199 running the name in "#RRGGBB" form
5200 "bg#" like "fg#" for "bg"
5201 "bold" "1" if bold
5202 "italic" "1" if italic
5203 "reverse" "1" if reverse
5204 "inverse" "1" if inverse (= reverse)
5205 "underline" "1" if underlined
5206 "undercurl" "1" if undercurled
5208 Example (echoes the color of the syntax item under the
5209 cursor): >
5210 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
5211 <
5212 synIDtrans({synID}) *synIDtrans()*
5213 The result is a Number, which is the translated syntax ID of
5214 {synID}. This is the syntax group ID of what is being used to
5215 highlight the character. Highlight links given with
5216 ":highlight link" are followed.
5218 synstack({lnum}, {col}) *synstack()*
5219 Return a |List|, which is the stack of syntax items at the
5220 position {lnum} and {col} in the current window. Each item in
5221 the List is an ID like what |synID()| returns.
5222 The first item in the List is the outer region, following are
5223 items contained in that one. The last one is what |synID()|
5224 returns, unless not the whole item is highlighted or it is a
5225 transparent item.
5226 This function is useful for debugging a syntax file.
5227 Example that shows the syntax stack under the cursor: >
5228 for id in synstack(line("."), col("."))
5229 echo synIDattr(id, "name")
5230 endfor
5232 system({expr} [, {input}]) *system()* *E677*
5233 Get the output of the shell command {expr}.
5234 When {input} is given, this string is written to a file and
5235 passed as stdin to the command. The string is written as-is,
5236 you need to take care of using the correct line separators
5237 yourself. Pipes are not used.
5238 Note: newlines in {expr} may cause the command to fail. The
5239 characters in 'shellquote' and 'shellxquote' may also cause
5240 trouble.
5241 This is not to be used for interactive commands.
5242 The result is a String. Example: >
5244 :let files = system("ls")
5246 < To make the result more system-independent, the shell output
5247 is filtered to replace <CR> with <NL> for Macintosh, and
5248 <CR><NL> with <NL> for DOS-like systems.
5249 The command executed is constructed using several options:
5250 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
5251 ({tmp} is an automatically generated file name).
5252 For Unix and OS/2 braces are put around {expr} to allow for
5253 concatenated commands.
5255 The command will be executed in "cooked" mode, so that a
5256 CTRL-C will interrupt the command (on Unix at least).
5258 The resulting error code can be found in |v:shell_error|.
5259 This function will fail in |restricted-mode|.
5261 Note that any wrong value in the options mentioned above may
5262 make the function fail. It has also been reported to fail
5263 when using a security agent application.
5264 Unlike ":!cmd" there is no automatic check for changed files.
5265 Use |:checktime| to force a check.
5268 tabpagebuflist([{arg}]) *tabpagebuflist()*
5269 The result is a |List|, where each item is the number of the
5270 buffer associated with each window in the current tab page.
5271 {arg} specifies the number of tab page to be used. When
5272 omitted the current tab page is used.
5273 When {arg} is invalid the number zero is returned.
5274 To get a list of all buffers in all tabs use this: >
5275 tablist = []
5276 for i in range(tabpagenr('$'))
5277 call extend(tablist, tabpagebuflist(i + 1))
5278 endfor
5279 < Note that a buffer may appear in more than one window.
5282 tabpagenr([{arg}]) *tabpagenr()*
5283 The result is a Number, which is the number of the current
5284 tab page. The first tab page has number 1.
5285 When the optional argument is "$", the number of the last tab
5286 page is returned (the tab page count).
5287 The number can be used with the |:tab| command.
5290 tabpagewinnr({tabarg}, [{arg}]) *tabpagewinnr()*
5291 Like |winnr()| but for tab page {arg}.
5292 {tabarg} specifies the number of tab page to be used.
5293 {arg} is used like with |winnr()|:
5294 - When omitted the current window number is returned. This is
5295 the window which will be used when going to this tab page.
5296 - When "$" the number of windows is returned.
5297 - When "#" the previous window nr is returned.
5298 Useful examples: >
5299 tabpagewinnr(1) " current window of tab page 1
5300 tabpagewinnr(4, '$') " number of windows in tab page 4
5301 < When {tabarg} is invalid zero is returned.
5303 *tagfiles()*
5304 tagfiles() Returns a |List| with the file names used to search for tags
5305 for the current buffer. This is the 'tags' option expanded.
5308 taglist({expr}) *taglist()*
5309 Returns a list of tags matching the regular expression {expr}.
5310 Each list item is a dictionary with at least the following
5311 entries:
5312 name Name of the tag.
5313 filename Name of the file where the tag is
5314 defined. It is either relative to the
5315 current directory or a full path.
5316 cmd Ex command used to locate the tag in
5317 the file.
5318 kind Type of the tag. The value for this
5319 entry depends on the language specific
5320 kind values. Only available when
5321 using a tags file generated by
5322 Exuberant ctags or hdrtag.
5323 static A file specific tag. Refer to
5324 |static-tag| for more information.
5325 More entries may be present, depending on the content of the
5326 tags file: access, implementation, inherits and signature.
5327 Refer to the ctags documentation for information about these
5328 fields. For C code the fields "struct", "class" and "enum"
5329 may appear, they give the name of the entity the tag is
5330 contained in.
5332 The ex-command 'cmd' can be either an ex search pattern, a
5333 line number or a line number followed by a byte number.
5335 If there are no matching tags, then an empty list is returned.
5337 To get an exact tag match, the anchors '^' and '$' should be
5338 used in {expr}. Refer to |tag-regexp| for more information
5339 about the tag search regular expression pattern.
5341 Refer to |'tags'| for information about how the tags file is
5342 located by Vim. Refer to |tags-file-format| for the format of
5343 the tags file generated by the different ctags tools.
5345 tempname() *tempname()* *temp-file-name*
5346 The result is a String, which is the name of a file that
5347 doesn't exist. It can be used for a temporary file. The name
5348 is different for at least 26 consecutive calls. Example: >
5349 :let tmpfile = tempname()
5350 :exe "redir > " . tmpfile
5351 < For Unix, the file will be in a private directory (only
5352 accessible by the current user) to avoid security problems
5353 (e.g., a symlink attack or other people reading your file).
5354 When Vim exits the directory and all files in it are deleted.
5355 For MS-Windows forward slashes are used when the 'shellslash'
5356 option is set or when 'shellcmdflag' starts with '-'.
5358 tolower({expr}) *tolower()*
5359 The result is a copy of the String given, with all uppercase
5360 characters turned into lowercase (just like applying |gu| to
5361 the string).
5363 toupper({expr}) *toupper()*
5364 The result is a copy of the String given, with all lowercase
5365 characters turned into uppercase (just like applying |gU| to
5366 the string).
5368 tr({src}, {fromstr}, {tostr}) *tr()*
5369 The result is a copy of the {src} string with all characters
5370 which appear in {fromstr} replaced by the character in that
5371 position in the {tostr} string. Thus the first character in
5372 {fromstr} is translated into the first character in {tostr}
5373 and so on. Exactly like the unix "tr" command.
5374 This code also deals with multibyte characters properly.
5376 Examples: >
5377 echo tr("hello there", "ht", "HT")
5378 < returns "Hello THere" >
5379 echo tr("<blob>", "<>", "{}")
5380 < returns "{blob}"
5382 trunc({expr}) *trunc()*
5383 Return the largest integral value with magnituted less than or
5384 equal to {expr} as a |Float| (truncate towards zero).
5385 {expr} must evaluate to a |Float| or a |Number|.
5386 Examples: >
5387 echo trunc(1.456)
5388 < 1.0 >
5389 echo trunc(-5.456)
5390 < -5.0 >
5391 echo trunc(4.0)
5392 < 4.0
5393 {only available when compiled with the |+float| feature}
5395 *type()*
5396 type({expr}) The result is a Number, depending on the type of {expr}:
5397 Number: 0
5398 String: 1
5399 Funcref: 2
5400 List: 3
5401 Dictionary: 4
5402 Float: 5
5403 To avoid the magic numbers it should be used this way: >
5404 :if type(myvar) == type(0)
5405 :if type(myvar) == type("")
5406 :if type(myvar) == type(function("tr"))
5407 :if type(myvar) == type([])
5408 :if type(myvar) == type({})
5409 :if type(myvar) == type(0.0)
5411 values({dict}) *values()*
5412 Return a |List| with all the values of {dict}. The |List| is
5413 in arbitrary order.
5416 virtcol({expr}) *virtcol()*
5417 The result is a Number, which is the screen column of the file
5418 position given with {expr}. That is, the last screen position
5419 occupied by the character at that position, when the screen
5420 would be of unlimited width. When there is a <Tab> at the
5421 position, the returned Number will be the column at the end of
5422 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
5423 set to 8, it returns 8.
5424 For the byte position use |col()|.
5425 For the use of {expr} see |col()|.
5426 When 'virtualedit' is used {expr} can be [lnum, col, off], where
5427 "off" is the offset in screen columns from the start of the
5428 character. E.g., a position within a <Tab> or after the last
5429 character.
5430 When Virtual editing is active in the current mode, a position
5431 beyond the end of the line can be returned. |'virtualedit'|
5432 The accepted positions are:
5433 . the cursor position
5434 $ the end of the cursor line (the result is the
5435 number of displayed characters in the cursor line
5436 plus one)
5437 'x position of mark x (if the mark is not set, 0 is
5438 returned)
5439 Note that only marks in the current file can be used.
5440 Examples: >
5441 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
5442 virtcol("$") with text "foo^Lbar", returns 9
5443 virtcol("'t") with text " there", with 't at 'h', returns 6
5444 < The first column is 1. 0 is returned for an error.
5445 A more advanced example that echoes the maximum length of
5446 all lines: >
5447 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
5450 visualmode([expr]) *visualmode()*
5451 The result is a String, which describes the last Visual mode
5452 used in the current buffer. Initially it returns an empty
5453 string, but once Visual mode has been used, it returns "v",
5454 "V", or "<CTRL-V>" (a single CTRL-V character) for
5455 character-wise, line-wise, or block-wise Visual mode
5456 respectively.
5457 Example: >
5458 :exe "normal " . visualmode()
5459 < This enters the same Visual mode as before. It is also useful
5460 in scripts if you wish to act differently depending on the
5461 Visual mode that was used.
5462 If Visual mode is active, use |mode()| to get the Visual mode
5463 (e.g., in a |:vmap|).
5465 If an expression is supplied that results in a non-zero number
5466 or a non-empty string, then the Visual mode will be cleared
5467 and the old value is returned. Note that " " and "0" are also
5468 non-empty strings, thus cause the mode to be cleared.
5470 *winbufnr()*
5471 winbufnr({nr}) The result is a Number, which is the number of the buffer
5472 associated with window {nr}. When {nr} is zero, the number of
5473 the buffer in the current window is returned. When window
5474 {nr} doesn't exist, -1 is returned.
5475 Example: >
5476 :echo "The file in the current window is " . bufname(winbufnr(0))
5477 <
5478 *wincol()*
5479 wincol() The result is a Number, which is the virtual column of the
5480 cursor in the window. This is counting screen cells from the
5481 left side of the window. The leftmost column is one.
5483 winheight({nr}) *winheight()*
5484 The result is a Number, which is the height of window {nr}.
5485 When {nr} is zero, the height of the current window is
5486 returned. When window {nr} doesn't exist, -1 is returned.
5487 An existing window always has a height of zero or more.
5488 Examples: >
5489 :echo "The current window has " . winheight(0) . " lines."
5490 <
5491 *winline()*
5492 winline() The result is a Number, which is the screen line of the cursor
5493 in the window. This is counting screen lines from the top of
5494 the window. The first line is one.
5495 If the cursor was moved the view on the file will be updated
5496 first, this may cause a scroll.
5498 *winnr()*
5499 winnr([{arg}]) The result is a Number, which is the number of the current
5500 window. The top window has number 1.
5501 When the optional argument is "$", the number of the
5502 last window is returned (the window count).
5503 When the optional argument is "#", the number of the last
5504 accessed window is returned (where |CTRL-W_p| goes to).
5505 If there is no previous window or it is in another tab page 0
5506 is returned.
5507 The number can be used with |CTRL-W_w| and ":wincmd w"
5508 |:wincmd|.
5509 Also see |tabpagewinnr()|.
5511 *winrestcmd()*
5512 winrestcmd() Returns a sequence of |:resize| commands that should restore
5513 the current window sizes. Only works properly when no windows
5514 are opened or closed and the current window and tab page is
5515 unchanged.
5516 Example: >
5517 :let cmd = winrestcmd()
5518 :call MessWithWindowSizes()
5519 :exe cmd
5520 <
5521 *winrestview()*
5522 winrestview({dict})
5523 Uses the |Dictionary| returned by |winsaveview()| to restore
5524 the view of the current window.
5525 If you have changed the values the result is unpredictable.
5526 If the window size changed the result won't be the same.
5528 *winsaveview()*
5529 winsaveview() Returns a |Dictionary| that contains information to restore
5530 the view of the current window. Use |winrestview()| to
5531 restore the view.
5532 This is useful if you have a mapping that jumps around in the
5533 buffer and you want to go back to the original view.
5534 This does not save fold information. Use the 'foldenable'
5535 option to temporarily switch off folding, so that folds are
5536 not opened when moving around.
5537 The return value includes:
5538 lnum cursor line number
5539 col cursor column
5540 coladd cursor column offset for 'virtualedit'
5541 curswant column for vertical movement
5542 topline first line in the window
5543 topfill filler lines, only in diff mode
5544 leftcol first column displayed
5545 skipcol columns skipped
5546 Note that no option values are saved.
5549 winwidth({nr}) *winwidth()*
5550 The result is a Number, which is the width of window {nr}.
5551 When {nr} is zero, the width of the current window is
5552 returned. When window {nr} doesn't exist, -1 is returned.
5553 An existing window always has a width of zero or more.
5554 Examples: >
5555 :echo "The current window has " . winwidth(0) . " columns."
5556 :if winwidth(0) <= 50
5557 : exe "normal 50\<C-W>|"
5558 :endif
5559 <
5560 *writefile()*
5561 writefile({list}, {fname} [, {binary}])
5562 Write |List| {list} to file {fname}. Each list item is
5563 separated with a NL. Each list item must be a String or
5564 Number.
5565 When {binary} is equal to "b" binary mode is used: There will
5566 not be a NL after the last list item. An empty item at the
5567 end does cause the last line in the file to end in a NL.
5568 All NL characters are replaced with a NUL character.
5569 Inserting CR characters needs to be done before passing {list}
5570 to writefile().
5571 An existing file is overwritten, if possible.
5572 When the write fails -1 is returned, otherwise 0. There is an
5573 error message if the file can't be created or when writing
5574 fails.
5575 Also see |readfile()|.
5576 To copy a file byte for byte: >
5577 :let fl = readfile("foo", "b")
5578 :call writefile(fl, "foocopy", "b")
5579 <
5581 *feature-list*
5582 There are three types of features:
5583 1. Features that are only supported when they have been enabled when Vim
5584 was compiled |+feature-list|. Example: >
5585 :if has("cindent")
5586 2. Features that are only supported when certain conditions have been met.
5587 Example: >
5588 :if has("gui_running")
5589 < *has-patch*
5590 3. Included patches. First check |v:version| for the version of Vim.
5591 Then the "patch123" feature means that patch 123 has been included for
5592 this version. Example (checking version 6.2.148 or later): >
5593 :if v:version > 602 || v:version == 602 && has("patch148")
5594 < Note that it's possible for patch 147 to be omitted even though 148 is
5595 included.
5597 all_builtin_terms Compiled with all builtin terminals enabled.
5598 amiga Amiga version of Vim.
5599 arabic Compiled with Arabic support |Arabic|.
5600 arp Compiled with ARP support (Amiga).
5601 autocmd Compiled with autocommand support. |autocommand|
5602 balloon_eval Compiled with |balloon-eval| support.
5603 balloon_multiline GUI supports multiline balloons.
5604 beos BeOS version of Vim.
5605 browse Compiled with |:browse| support, and browse() will
5606 work.
5607 builtin_terms Compiled with some builtin terminals.
5608 byte_offset Compiled with support for 'o' in 'statusline'
5609 cindent Compiled with 'cindent' support.
5610 clientserver Compiled with remote invocation support |clientserver|.
5611 clipboard Compiled with 'clipboard' support.
5612 cmdline_compl Compiled with |cmdline-completion| support.
5613 cmdline_hist Compiled with |cmdline-history| support.
5614 cmdline_info Compiled with 'showcmd' and 'ruler' support.
5615 comments Compiled with |'comments'| support.
5616 cryptv Compiled with encryption support |encryption|.
5617 cscope Compiled with |cscope| support.
5618 compatible Compiled to be very Vi compatible.
5619 debug Compiled with "DEBUG" defined.
5620 dialog_con Compiled with console dialog support.
5621 dialog_gui Compiled with GUI dialog support.
5622 diff Compiled with |vimdiff| and 'diff' support.
5623 digraphs Compiled with support for digraphs.
5624 dnd Compiled with support for the "~ register |quote_~|.
5625 dos32 32 bits DOS (DJGPP) version of Vim.
5626 dos16 16 bits DOS version of Vim.
5627 ebcdic Compiled on a machine with ebcdic character set.
5628 emacs_tags Compiled with support for Emacs tags.
5629 eval Compiled with expression evaluation support. Always
5630 true, of course!
5631 ex_extra Compiled with extra Ex commands |+ex_extra|.
5632 extra_search Compiled with support for |'incsearch'| and
5633 |'hlsearch'|
5634 farsi Compiled with Farsi support |farsi|.
5635 file_in_path Compiled with support for |gf| and |<cfile>|
5636 filterpipe When 'shelltemp' is off pipes are used for shell
5637 read/write/filter commands
5638 find_in_path Compiled with support for include file searches
5639 |+find_in_path|.
5640 float Compiled with support for |Float|.
5641 fname_case Case in file names matters (for Amiga, MS-DOS, and
5642 Windows this is not present).
5643 folding Compiled with |folding| support.
5644 footer Compiled with GUI footer support. |gui-footer|
5645 fork Compiled to use fork()/exec() instead of system().
5646 gettext Compiled with message translation |multi-lang|
5647 gui Compiled with GUI enabled.
5648 gui_athena Compiled with Athena GUI.
5649 gui_gtk Compiled with GTK+ GUI (any version).
5650 gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
5651 gui_gnome Compiled with Gnome support (gui_gtk is also defined).
5652 gui_mac Compiled with Macintosh GUI.
5653 gui_motif Compiled with Motif GUI.
5654 gui_photon Compiled with Photon GUI.
5655 gui_win32 Compiled with MS Windows Win32 GUI.
5656 gui_win32s idem, and Win32s system being used (Windows 3.1)
5657 gui_running Vim is running in the GUI, or it will start soon.
5658 hangul_input Compiled with Hangul input support. |hangul|
5659 iconv Can use iconv() for conversion.
5660 insert_expand Compiled with support for CTRL-X expansion commands in
5661 Insert mode.
5662 jumplist Compiled with |jumplist| support.
5663 keymap Compiled with 'keymap' support.
5664 langmap Compiled with 'langmap' support.
5665 libcall Compiled with |libcall()| support.
5666 linebreak Compiled with 'linebreak', 'breakat' and 'showbreak'
5667 support.
5668 lispindent Compiled with support for lisp indenting.
5669 listcmds Compiled with commands for the buffer list |:files|
5670 and the argument list |arglist|.
5671 localmap Compiled with local mappings and abbr. |:map-local|
5672 mac Macintosh version of Vim.
5673 macunix Macintosh version of Vim, using Unix files (OS-X).
5674 menu Compiled with support for |:menu|.
5675 mksession Compiled with support for |:mksession|.
5676 modify_fname Compiled with file name modifiers. |filename-modifiers|
5677 mouse Compiled with support mouse.
5678 mouseshape Compiled with support for 'mouseshape'.
5679 mouse_dec Compiled with support for Dec terminal mouse.
5680 mouse_gpm Compiled with support for gpm (Linux console mouse)
5681 mouse_netterm Compiled with support for netterm mouse.
5682 mouse_pterm Compiled with support for qnx pterm mouse.
5683 mouse_xterm Compiled with support for xterm mouse.
5684 multi_byte Compiled with support for editing Korean et al.
5685 multi_byte_ime Compiled with support for IME input method.
5686 multi_lang Compiled with support for multiple languages.
5687 mzscheme Compiled with MzScheme interface |mzscheme|.
5688 netbeans_intg Compiled with support for |netbeans|.
5689 netbeans_enabled Compiled with support for |netbeans| and it's used.
5690 ole Compiled with OLE automation support for Win32.
5691 os2 OS/2 version of Vim.
5692 osfiletype Compiled with support for osfiletypes |+osfiletype|
5693 path_extra Compiled with up/downwards search in 'path' and 'tags'
5694 perl Compiled with Perl interface.
5695 postscript Compiled with PostScript file printing.
5696 printer Compiled with |:hardcopy| support.
5697 profile Compiled with |:profile| support.
5698 python Compiled with Python interface.
5699 qnx QNX version of Vim.
5700 quickfix Compiled with |quickfix| support.
5701 reltime Compiled with |reltime()| support.
5702 rightleft Compiled with 'rightleft' support.
5703 ruby Compiled with Ruby interface |ruby|.
5704 scrollbind Compiled with 'scrollbind' support.
5705 showcmd Compiled with 'showcmd' support.
5706 signs Compiled with |:sign| support.
5707 smartindent Compiled with 'smartindent' support.
5708 sniff Compiled with SNiFF interface support.
5709 statusline Compiled with support for 'statusline', 'rulerformat'
5710 and special formats of 'titlestring' and 'iconstring'.
5711 sun_workshop Compiled with support for Sun |workshop|.
5712 spell Compiled with spell checking support |spell|.
5713 syntax Compiled with syntax highlighting support |syntax|.
5714 syntax_items There are active syntax highlighting items for the
5715 current buffer.
5716 system Compiled to use system() instead of fork()/exec().
5717 tag_binary Compiled with binary searching in tags files
5718 |tag-binary-search|.
5719 tag_old_static Compiled with support for old static tags
5720 |tag-old-static|.
5721 tag_any_white Compiled with support for any white characters in tags
5722 files |tag-any-white|.
5723 tcl Compiled with Tcl interface.
5724 terminfo Compiled with terminfo instead of termcap.
5725 termresponse Compiled with support for |t_RV| and |v:termresponse|.
5726 textobjects Compiled with support for |text-objects|.
5727 tgetent Compiled with tgetent support, able to use a termcap
5728 or terminfo file.
5729 title Compiled with window title support |'title'|.
5730 toolbar Compiled with support for |gui-toolbar|.
5731 unix Unix version of Vim.
5732 user_commands User-defined commands.
5733 viminfo Compiled with viminfo support.
5734 vim_starting True while initial source'ing takes place.
5735 vertsplit Compiled with vertically split windows |:vsplit|.
5736 virtualedit Compiled with 'virtualedit' option.
5737 visual Compiled with Visual mode.
5738 visualextra Compiled with extra Visual mode commands.
5739 |blockwise-operators|.
5740 vms VMS version of Vim.
5741 vreplace Compiled with |gR| and |gr| commands.
5742 wildignore Compiled with 'wildignore' option.
5743 wildmenu Compiled with 'wildmenu' option.
5744 windows Compiled with support for more than one window.
5745 winaltkeys Compiled with 'winaltkeys' option.
5746 win16 Win16 version of Vim (MS-Windows 3.1).
5747 win32 Win32 version of Vim (MS-Windows 95/98/ME/NT/2000/XP).
5748 win64 Win64 version of Vim (MS-Windows 64 bit).
5749 win32unix Win32 version of Vim, using Unix files (Cygwin)
5750 win95 Win32 version for MS-Windows 95/98/ME.
5751 writebackup Compiled with 'writebackup' default on.
5752 xfontset Compiled with X fontset support |xfontset|.
5753 xim Compiled with X input method support |xim|.
5754 xsmp Compiled with X session management support.
5755 xsmp_interact Compiled with interactive X session management support.
5756 xterm_clipboard Compiled with support for xterm clipboard.
5757 xterm_save Compiled with support for saving and restoring the
5758 xterm screen.
5759 x11 Compiled with X11 support.
5761 *string-match*
5762 Matching a pattern in a String
5764 A regexp pattern as explained at |pattern| is normally used to find a match in
5765 the buffer lines. When a pattern is used to find a match in a String, almost
5766 everything works in the same way. The difference is that a String is handled
5767 like it is one line. When it contains a "\n" character, this is not seen as a
5768 line break for the pattern. It can be matched with a "\n" in the pattern, or
5769 with ".". Example: >
5770 :let a = "aaaa\nxxxx"
5771 :echo matchstr(a, "..\n..")
5772 aa
5773 xx
5774 :echo matchstr(a, "a.x")
5775 a
5776 x
5778 Don't forget that "^" will only match at the first character of the String and
5779 "$" at the last character of the string. They don't match after or before a
5780 "\n".
5782 ==============================================================================
5783 5. Defining functions *user-functions*
5785 New functions can be defined. These can be called just like builtin
5786 functions. The function executes a sequence of Ex commands. Normal mode
5787 commands can be executed with the |:normal| command.
5789 The function name must start with an uppercase letter, to avoid confusion with
5790 builtin functions. To prevent from using the same name in different scripts
5791 avoid obvious, short names. A good habit is to start the function name with
5792 the name of the script, e.g., "HTMLcolor()".
5794 It's also possible to use curly braces, see |curly-braces-names|. And the
5795 |autoload| facility is useful to define a function only when it's called.
5797 *local-function*
5798 A function local to a script must start with "s:". A local script function
5799 can only be called from within the script and from functions, user commands
5800 and autocommands defined in the script. It is also possible to call the
5801 function from a mappings defined in the script, but then |<SID>| must be used
5802 instead of "s:" when the mapping is expanded outside of the script.
5804 *:fu* *:function* *E128* *E129* *E123*
5805 :fu[nction] List all functions and their arguments.
5807 :fu[nction] {name} List function {name}.
5808 {name} can also be a |Dictionary| entry that is a
5809 |Funcref|: >
5810 :function dict.init
5812 :fu[nction] /{pattern} List functions with a name matching {pattern}.
5813 Example that lists all functions ending with "File": >
5814 :function /File$
5815 <
5816 *:function-verbose*
5817 When 'verbose' is non-zero, listing a function will also display where it was
5818 last defined. Example: >
5820 :verbose function SetFileTypeSH
5821 function SetFileTypeSH(name)
5822 Last set from /usr/share/vim/vim-7.0/filetype.vim
5823 <
5824 See |:verbose-cmd| for more information.
5826 *E124* *E125*
5827 :fu[nction][!] {name}([arguments]) [range] [abort] [dict]
5828 Define a new function by the name {name}. The name
5829 must be made of alphanumeric characters and '_', and
5830 must start with a capital or "s:" (see above).
5832 {name} can also be a |Dictionary| entry that is a
5833 |Funcref|: >
5834 :function dict.init(arg)
5835 < "dict" must be an existing dictionary. The entry
5836 "init" is added if it didn't exist yet. Otherwise [!]
5837 is required to overwrite an existing function. The
5838 result is a |Funcref| to a numbered function. The
5839 function can only be used with a |Funcref| and will be
5840 deleted if there are no more references to it.
5841 *E127* *E122*
5842 When a function by this name already exists and [!] is
5843 not used an error message is given. When [!] is used,
5844 an existing function is silently replaced. Unless it
5845 is currently being executed, that is an error.
5847 For the {arguments} see |function-argument|.
5849 *a:firstline* *a:lastline*
5850 When the [range] argument is added, the function is
5851 expected to take care of a range itself. The range is
5852 passed as "a:firstline" and "a:lastline". If [range]
5853 is excluded, ":{range}call" will call the function for
5854 each line in the range, with the cursor on the start
5855 of each line. See |function-range-example|.
5857 When the [abort] argument is added, the function will
5858 abort as soon as an error is detected.
5860 When the [dict] argument is added, the function must
5861 be invoked through an entry in a |Dictionary|. The
5862 local variable "self" will then be set to the
5863 dictionary. See |Dictionary-function|.
5865 The last used search pattern and the redo command "."
5866 will not be changed by the function. This also
5867 implies that the effect of |:nohlsearch| is undone
5868 when the function returns.
5870 *:endf* *:endfunction* *E126* *E193*
5871 :endf[unction] The end of a function definition. Must be on a line
5872 by its own, without other commands.
5874 *:delf* *:delfunction* *E130* *E131*
5875 :delf[unction] {name} Delete function {name}.
5876 {name} can also be a |Dictionary| entry that is a
5877 |Funcref|: >
5878 :delfunc dict.init
5879 < This will remove the "init" entry from "dict". The
5880 function is deleted if there are no more references to
5881 it.
5882 *:retu* *:return* *E133*
5883 :retu[rn] [expr] Return from a function. When "[expr]" is given, it is
5884 evaluated and returned as the result of the function.
5885 If "[expr]" is not given, the number 0 is returned.
5886 When a function ends without an explicit ":return",
5887 the number 0 is returned.
5888 Note that there is no check for unreachable lines,
5889 thus there is no warning if commands follow ":return".
5891 If the ":return" is used after a |:try| but before the
5892 matching |:finally| (if present), the commands
5893 following the ":finally" up to the matching |:endtry|
5894 are executed first. This process applies to all
5895 nested ":try"s inside the function. The function
5896 returns at the outermost ":endtry".
5898 *function-argument* *a:var*
5899 An argument can be defined by giving its name. In the function this can then
5900 be used as "a:name" ("a:" for argument).
5901 *a:0* *a:1* *a:000* *E740* *...*
5902 Up to 20 arguments can be given, separated by commas. After the named
5903 arguments an argument "..." can be specified, which means that more arguments
5904 may optionally be following. In the function the extra arguments can be used
5905 as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which
5906 can be 0). "a:000" is set to a |List| that contains these arguments. Note
5907 that "a:1" is the same as "a:000[0]".
5908 *E742*
5909 The a: scope and the variables in it cannot be changed, they are fixed.
5910 However, if a |List| or |Dictionary| is used, you can changes their contents.
5911 Thus you can pass a |List| to a function and have the function add an item to
5912 it. If you want to make sure the function cannot change a |List| or
5913 |Dictionary| use |:lockvar|.
5915 When not using "...", the number of arguments in a function call must be equal
5916 to the number of named arguments. When using "...", the number of arguments
5917 may be larger.
5919 It is also possible to define a function without any arguments. You must
5920 still supply the () then. The body of the function follows in the next lines,
5921 until the matching |:endfunction|. It is allowed to define another function
5922 inside a function body.
5924 *local-variables*
5925 Inside a function variables can be used. These are local variables, which
5926 will disappear when the function returns. Global variables need to be
5927 accessed with "g:".
5929 Example: >
5930 :function Table(title, ...)
5931 : echohl Title
5932 : echo a:title
5933 : echohl None
5934 : echo a:0 . " items:"
5935 : for s in a:000
5936 : echon ' ' . s
5937 : endfor
5938 :endfunction
5940 This function can then be called with: >
5941 call Table("Table", "line1", "line2")
5942 call Table("Empty Table")
5944 To return more than one value, return a |List|: >
5945 :function Compute(n1, n2)
5946 : if a:n2 == 0
5947 : return ["fail", 0]
5948 : endif
5949 : return ["ok", a:n1 / a:n2]
5950 :endfunction
5952 This function can then be called with: >
5953 :let [success, div] = Compute(102, 6)
5954 :if success == "ok"
5955 : echo div
5956 :endif
5957 <
5958 *:cal* *:call* *E107* *E117*
5959 :[range]cal[l] {name}([arguments])
5960 Call a function. The name of the function and its arguments
5961 are as specified with |:function|. Up to 20 arguments can be
5962 used. The returned value is discarded.
5963 Without a range and for functions that accept a range, the
5964 function is called once. When a range is given the cursor is
5965 positioned at the start of the first line before executing the
5966 function.
5967 When a range is given and the function doesn't handle it
5968 itself, the function is executed for each line in the range,
5969 with the cursor in the first column of that line. The cursor
5970 is left at the last line (possibly moved by the last function
5971 call). The arguments are re-evaluated for each line. Thus
5972 this works:
5973 *function-range-example* >
5974 :function Mynumber(arg)
5975 : echo line(".") . " " . a:arg
5976 :endfunction
5977 :1,5call Mynumber(getline("."))
5978 <
5979 The "a:firstline" and "a:lastline" are defined anyway, they
5980 can be used to do something different at the start or end of
5981 the range.
5983 Example of a function that handles the range itself: >
5985 :function Cont() range
5986 : execute (a:firstline + 1) . "," . a:lastline . 's/^/\t\\ '
5987 :endfunction
5988 :4,8call Cont()
5989 <
5990 This function inserts the continuation character "\" in front
5991 of all the lines in the range, except the first one.
5993 When the function returns a composite value it can be further
5994 dereferenced, but the range will not be used then. Example: >
5995 :4,8call GetDict().method()
5996 < Here GetDict() gets the range but method() does not.
5998 *E132*
5999 The recursiveness of user functions is restricted with the |'maxfuncdepth'|
6000 option.
6003 AUTOMATICALLY LOADING FUNCTIONS ~
6004 *autoload-functions*
6005 When using many or large functions, it's possible to automatically define them
6006 only when they are used. There are two methods: with an autocommand and with
6007 the "autoload" directory in 'runtimepath'.
6010 Using an autocommand ~
6012 This is introduced in the user manual, section |41.14|.
6014 The autocommand is useful if you have a plugin that is a long Vim script file.
6015 You can define the autocommand and quickly quit the script with |:finish|.
6016 That makes Vim startup faster. The autocommand should then load the same file
6017 again, setting a variable to skip the |:finish| command.
6019 Use the FuncUndefined autocommand event with a pattern that matches the
6020 function(s) to be defined. Example: >
6022 :au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
6024 The file "~/vim/bufnetfuncs.vim" should then define functions that start with
6025 "BufNet". Also see |FuncUndefined|.
6028 Using an autoload script ~
6029 *autoload* *E746*
6030 This is introduced in the user manual, section |41.15|.
6032 Using a script in the "autoload" directory is simpler, but requires using
6033 exactly the right file name. A function that can be autoloaded has a name
6034 like this: >
6036 :call filename#funcname()
6038 When such a function is called, and it is not defined yet, Vim will search the
6039 "autoload" directories in 'runtimepath' for a script file called
6040 "filename.vim". For example "~/.vim/autoload/filename.vim". That file should
6041 then define the function like this: >
6043 function filename#funcname()
6044 echo "Done!"
6045 endfunction
6047 The file name and the name used before the # in the function must match
6048 exactly, and the defined function must have the name exactly as it will be
6049 called.
6051 It is possible to use subdirectories. Every # in the function name works like
6052 a path separator. Thus when calling a function: >
6054 :call foo#bar#func()
6056 Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
6058 This also works when reading a variable that has not been set yet: >
6060 :let l = foo#bar#lvar
6062 However, when the autoload script was already loaded it won't be loaded again
6063 for an unknown variable.
6065 When assigning a value to such a variable nothing special happens. This can
6066 be used to pass settings to the autoload script before it's loaded: >
6068 :let foo#bar#toggle = 1
6069 :call foo#bar#func()
6071 Note that when you make a mistake and call a function that is supposed to be
6072 defined in an autoload script, but the script doesn't actually define the
6073 function, the script will be sourced every time you try to call the function.
6074 And you will get an error message every time.
6076 Also note that if you have two script files, and one calls a function in the
6077 other and vice versa, before the used function is defined, it won't work.
6078 Avoid using the autoload functionality at the toplevel.
6080 Hint: If you distribute a bunch of scripts you can pack them together with the
6081 |vimball| utility. Also read the user manual |distribute-script|.
6083 ==============================================================================
6084 6. Curly braces names *curly-braces-names*
6086 Wherever you can use a variable, you can use a "curly braces name" variable.
6087 This is a regular variable name with one or more expressions wrapped in braces
6088 {} like this: >
6089 my_{adjective}_variable
6091 When Vim encounters this, it evaluates the expression inside the braces, puts
6092 that in place of the expression, and re-interprets the whole as a variable
6093 name. So in the above example, if the variable "adjective" was set to
6094 "noisy", then the reference would be to "my_noisy_variable", whereas if
6095 "adjective" was set to "quiet", then it would be to "my_quiet_variable".
6097 One application for this is to create a set of variables governed by an option
6098 value. For example, the statement >
6099 echo my_{&background}_message
6101 would output the contents of "my_dark_message" or "my_light_message" depending
6102 on the current value of 'background'.
6104 You can use multiple brace pairs: >
6105 echo my_{adverb}_{adjective}_message
6106 ..or even nest them: >
6107 echo my_{ad{end_of_word}}_message
6108 where "end_of_word" is either "verb" or "jective".
6110 However, the expression inside the braces must evaluate to a valid single
6111 variable name, e.g. this is invalid: >
6112 :let foo='a + b'
6113 :echo c{foo}d
6114 .. since the result of expansion is "ca + bd", which is not a variable name.
6116 *curly-braces-function-names*
6117 You can call and define functions by an evaluated name in a similar way.
6118 Example: >
6119 :let func_end='whizz'
6120 :call my_func_{func_end}(parameter)
6122 This would call the function "my_func_whizz(parameter)".
6124 ==============================================================================
6125 7. Commands *expression-commands*
6127 :let {var-name} = {expr1} *:let* *E18*
6128 Set internal variable {var-name} to the result of the
6129 expression {expr1}. The variable will get the type
6130 from the {expr}. If {var-name} didn't exist yet, it
6131 is created.
6133 :let {var-name}[{idx}] = {expr1} *E689*
6134 Set a list item to the result of the expression
6135 {expr1}. {var-name} must refer to a list and {idx}
6136 must be a valid index in that list. For nested list
6137 the index can be repeated.
6138 This cannot be used to add an item to a |List|.
6139 This cannot be used to set a byte in a String. You
6140 can do that like this: >
6141 :let var = var[0:2] . 'X' . var[4:]
6142 <
6143 *E711* *E719*
6144 :let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710*
6145 Set a sequence of items in a |List| to the result of
6146 the expression {expr1}, which must be a list with the
6147 correct number of items.
6148 {idx1} can be omitted, zero is used instead.
6149 {idx2} can be omitted, meaning the end of the list.
6150 When the selected range of items is partly past the
6151 end of the list, items will be added.
6153 *:let+=* *:let-=* *:let.=* *E734*
6154 :let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
6155 :let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
6156 :let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
6157 These fail if {var} was not set yet and when the type
6158 of {var} and {expr1} don't fit the operator.
6161 :let ${env-name} = {expr1} *:let-environment* *:let-$*
6162 Set environment variable {env-name} to the result of
6163 the expression {expr1}. The type is always String.
6164 :let ${env-name} .= {expr1}
6165 Append {expr1} to the environment variable {env-name}.
6166 If the environment variable didn't exist yet this
6167 works like "=".
6169 :let @{reg-name} = {expr1} *:let-register* *:let-@*
6170 Write the result of the expression {expr1} in register
6171 {reg-name}. {reg-name} must be a single letter, and
6172 must be the name of a writable register (see
6173 |registers|). "@@" can be used for the unnamed
6174 register, "@/" for the search pattern.
6175 If the result of {expr1} ends in a <CR> or <NL>, the
6176 register will be linewise, otherwise it will be set to
6177 characterwise.
6178 This can be used to clear the last search pattern: >
6179 :let @/ = ""
6180 < This is different from searching for an empty string,
6181 that would match everywhere.
6183 :let @{reg-name} .= {expr1}
6184 Append {expr1} to register {reg-name}. If the
6185 register was empty it's like setting it to {expr1}.
6187 :let &{option-name} = {expr1} *:let-option* *:let-&*
6188 Set option {option-name} to the result of the
6189 expression {expr1}. A String or Number value is
6190 always converted to the type of the option.
6191 For an option local to a window or buffer the effect
6192 is just like using the |:set| command: both the local
6193 value and the global value are changed.
6194 Example: >
6195 :let &path = &path . ',/usr/local/include'
6197 :let &{option-name} .= {expr1}
6198 For a string option: Append {expr1} to the value.
6199 Does not insert a comma like |:set+=|.
6201 :let &{option-name} += {expr1}
6202 :let &{option-name} -= {expr1}
6203 For a number or boolean option: Add or subtract
6204 {expr1}.
6206 :let &l:{option-name} = {expr1}
6207 :let &l:{option-name} .= {expr1}
6208 :let &l:{option-name} += {expr1}
6209 :let &l:{option-name} -= {expr1}
6210 Like above, but only set the local value of an option
6211 (if there is one). Works like |:setlocal|.
6213 :let &g:{option-name} = {expr1}
6214 :let &g:{option-name} .= {expr1}
6215 :let &g:{option-name} += {expr1}
6216 :let &g:{option-name} -= {expr1}
6217 Like above, but only set the global value of an option
6218 (if there is one). Works like |:setglobal|.
6220 :let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
6221 {expr1} must evaluate to a |List|. The first item in
6222 the list is assigned to {name1}, the second item to
6223 {name2}, etc.
6224 The number of names must match the number of items in
6225 the |List|.
6226 Each name can be one of the items of the ":let"
6227 command as mentioned above.
6228 Example: >
6229 :let [s, item] = GetItem(s)
6230 < Detail: {expr1} is evaluated first, then the
6231 assignments are done in sequence. This matters if
6232 {name2} depends on {name1}. Example: >
6233 :let x = [0, 1]
6234 :let i = 0
6235 :let [i, x[i]] = [1, 2]
6236 :echo x
6237 < The result is [0, 2].
6239 :let [{name1}, {name2}, ...] .= {expr1}
6240 :let [{name1}, {name2}, ...] += {expr1}
6241 :let [{name1}, {name2}, ...] -= {expr1}
6242 Like above, but append/add/subtract the value for each
6243 |List| item.
6245 :let [{name}, ..., ; {lastname}] = {expr1}
6246 Like |:let-unpack| above, but the |List| may have more
6247 items than there are names. A list of the remaining
6248 items is assigned to {lastname}. If there are no
6249 remaining items {lastname} is set to an empty list.
6250 Example: >
6251 :let [a, b; rest] = ["aval", "bval", 3, 4]
6252 <
6253 :let [{name}, ..., ; {lastname}] .= {expr1}
6254 :let [{name}, ..., ; {lastname}] += {expr1}
6255 :let [{name}, ..., ; {lastname}] -= {expr1}
6256 Like above, but append/add/subtract the value for each
6257 |List| item.
6258 *E106*
6259 :let {var-name} .. List the value of variable {var-name}. Multiple
6260 variable names may be given. Special names recognized
6261 here: *E738*
6262 g: global variables
6263 b: local buffer variables
6264 w: local window variables
6265 t: local tab page variables
6266 s: script-local variables
6267 l: local function variables
6268 v: Vim variables.
6270 :let List the values of all variables. The type of the
6271 variable is indicated before the value:
6272 <nothing> String
6273 # Number
6274 * Funcref
6277 :unl[et][!] {name} ... *:unlet* *:unl* *E108* *E795*
6278 Remove the internal variable {name}. Several variable
6279 names can be given, they are all removed. The name
6280 may also be a |List| or |Dictionary| item.
6281 With [!] no error message is given for non-existing
6282 variables.
6283 One or more items from a |List| can be removed: >
6284 :unlet list[3] " remove fourth item
6285 :unlet list[3:] " remove fourth item to last
6286 < One item from a |Dictionary| can be removed at a time: >
6287 :unlet dict['two']
6288 :unlet dict.two
6290 :lockv[ar][!] [depth] {name} ... *:lockvar* *:lockv*
6291 Lock the internal variable {name}. Locking means that
6292 it can no longer be changed (until it is unlocked).
6293 A locked variable can be deleted: >
6294 :lockvar v
6295 :let v = 'asdf' " fails!
6296 :unlet v
6297 < *E741*
6298 If you try to change a locked variable you get an
6299 error message: "E741: Value of {name} is locked"
6301 [depth] is relevant when locking a |List| or
6302 |Dictionary|. It specifies how deep the locking goes:
6303 1 Lock the |List| or |Dictionary| itself,
6304 cannot add or remove items, but can
6305 still change their values.
6306 2 Also lock the values, cannot change
6307 the items. If an item is a |List| or
6308 |Dictionary|, cannot add or remove
6309 items, but can still change the
6310 values.
6311 3 Like 2 but for the |List| /
6312 |Dictionary| in the |List| /
6313 |Dictionary|, one level deeper.
6314 The default [depth] is 2, thus when {name} is a |List|
6315 or |Dictionary| the values cannot be changed.
6316 *E743*
6317 For unlimited depth use [!] and omit [depth].
6318 However, there is a maximum depth of 100 to catch
6319 loops.
6321 Note that when two variables refer to the same |List|
6322 and you lock one of them, the |List| will also be
6323 locked when used through the other variable.
6324 Example: >
6325 :let l = [0, 1, 2, 3]
6326 :let cl = l
6327 :lockvar l
6328 :let cl[1] = 99 " won't work!
6329 < You may want to make a copy of a list to avoid this.
6330 See |deepcopy()|.
6333 :unlo[ckvar][!] [depth] {name} ... *:unlockvar* *:unlo*
6334 Unlock the internal variable {name}. Does the
6335 opposite of |:lockvar|.
6338 :if {expr1} *:if* *:endif* *:en* *E171* *E579* *E580*
6339 :en[dif] Execute the commands until the next matching ":else"
6340 or ":endif" if {expr1} evaluates to non-zero.
6342 From Vim version 4.5 until 5.0, every Ex command in
6343 between the ":if" and ":endif" is ignored. These two
6344 commands were just to allow for future expansions in a
6345 backwards compatible way. Nesting was allowed. Note
6346 that any ":else" or ":elseif" was ignored, the "else"
6347 part was not executed either.
6349 You can use this to remain compatible with older
6350 versions: >
6351 :if version >= 500
6352 : version-5-specific-commands
6353 :endif
6354 < The commands still need to be parsed to find the
6355 "endif". Sometimes an older Vim has a problem with a
6356 new command. For example, ":silent" is recognized as
6357 a ":substitute" command. In that case ":execute" can
6358 avoid problems: >
6359 :if version >= 600
6360 : execute "silent 1,$delete"
6361 :endif
6362 <
6363 NOTE: The ":append" and ":insert" commands don't work
6364 properly in between ":if" and ":endif".
6366 *:else* *:el* *E581* *E583*
6367 :el[se] Execute the commands until the next matching ":else"
6368 or ":endif" if they previously were not being
6369 executed.
6371 *:elseif* *:elsei* *E582* *E584*
6372 :elsei[f] {expr1} Short for ":else" ":if", with the addition that there
6373 is no extra ":endif".
6375 :wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw*
6376 *E170* *E585* *E588* *E733*
6377 :endw[hile] Repeat the commands between ":while" and ":endwhile",
6378 as long as {expr1} evaluates to non-zero.
6379 When an error is detected from a command inside the
6380 loop, execution continues after the "endwhile".
6381 Example: >
6382 :let lnum = 1
6383 :while lnum <= line("$")
6384 :call FixLine(lnum)
6385 :let lnum = lnum + 1
6386 :endwhile
6387 <
6388 NOTE: The ":append" and ":insert" commands don't work
6389 properly inside a ":while" and ":for" loop.
6391 :for {var} in {list} *:for* *E690* *E732*
6392 :endfo[r] *:endfo* *:endfor*
6393 Repeat the commands between ":for" and ":endfor" for
6394 each item in {list}. Variable {var} is set to the
6395 value of each item.
6396 When an error is detected for a command inside the
6397 loop, execution continues after the "endfor".
6398 Changing {list} inside the loop affects what items are
6399 used. Make a copy if this is unwanted: >
6400 :for item in copy(mylist)
6401 < When not making a copy, Vim stores a reference to the
6402 next item in the list, before executing the commands
6403 with the current item. Thus the current item can be
6404 removed without effect. Removing any later item means
6405 it will not be found. Thus the following example
6406 works (an inefficient way to make a list empty): >
6407 :for item in mylist
6408 :call remove(mylist, 0)
6409 :endfor
6410 < Note that reordering the list (e.g., with sort() or
6411 reverse()) may have unexpected effects.
6412 Note that the type of each list item should be
6413 identical to avoid errors for the type of {var}
6414 changing. Unlet the variable at the end of the loop
6415 to allow multiple item types.
6417 :for [{var1}, {var2}, ...] in {listlist}
6418 :endfo[r]
6419 Like ":for" above, but each item in {listlist} must be
6420 a list, of which each item is assigned to {var1},
6421 {var2}, etc. Example: >
6422 :for [lnum, col] in [[1, 3], [2, 5], [3, 8]]
6423 :echo getline(lnum)[col]
6424 :endfor
6425 <
6426 *:continue* *:con* *E586*
6427 :con[tinue] When used inside a ":while" or ":for" loop, jumps back
6428 to the start of the loop.
6429 If it is used after a |:try| inside the loop but
6430 before the matching |:finally| (if present), the
6431 commands following the ":finally" up to the matching
6432 |:endtry| are executed first. This process applies to
6433 all nested ":try"s inside the loop. The outermost
6434 ":endtry" then jumps back to the start of the loop.
6436 *:break* *:brea* *E587*
6437 :brea[k] When used inside a ":while" or ":for" loop, skips to
6438 the command after the matching ":endwhile" or
6439 ":endfor".
6440 If it is used after a |:try| inside the loop but
6441 before the matching |:finally| (if present), the
6442 commands following the ":finally" up to the matching
6443 |:endtry| are executed first. This process applies to
6444 all nested ":try"s inside the loop. The outermost
6445 ":endtry" then jumps to the command after the loop.
6447 :try *:try* *:endt* *:endtry* *E600* *E601* *E602*
6448 :endt[ry] Change the error handling for the commands between
6449 ":try" and ":endtry" including everything being
6450 executed across ":source" commands, function calls,
6451 or autocommand invocations.
6453 When an error or interrupt is detected and there is
6454 a |:finally| command following, execution continues
6455 after the ":finally". Otherwise, or when the
6456 ":endtry" is reached thereafter, the next
6457 (dynamically) surrounding ":try" is checked for
6458 a corresponding ":finally" etc. Then the script
6459 processing is terminated. (Whether a function
6460 definition has an "abort" argument does not matter.)
6461 Example: >
6462 :try | edit too much | finally | echo "cleanup" | endtry
6463 :echo "impossible" " not reached, script terminated above
6464 <
6465 Moreover, an error or interrupt (dynamically) inside
6466 ":try" and ":endtry" is converted to an exception. It
6467 can be caught as if it were thrown by a |:throw|
6468 command (see |:catch|). In this case, the script
6469 processing is not terminated.
6471 The value "Vim:Interrupt" is used for an interrupt
6472 exception. An error in a Vim command is converted
6473 to a value of the form "Vim({command}):{errmsg}",
6474 other errors are converted to a value of the form
6475 "Vim:{errmsg}". {command} is the full command name,
6476 and {errmsg} is the message that is displayed if the
6477 error exception is not caught, always beginning with
6478 the error number.
6479 Examples: >
6480 :try | sleep 100 | catch /^Vim:Interrupt$/ | endtry
6481 :try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry
6482 <
6483 *:cat* *:catch* *E603* *E604* *E605*
6484 :cat[ch] /{pattern}/ The following commands until the next ":catch",
6485 |:finally|, or |:endtry| that belongs to the same
6486 |:try| as the ":catch" are executed when an exception
6487 matching {pattern} is being thrown and has not yet
6488 been caught by a previous ":catch". Otherwise, these
6489 commands are skipped.
6490 When {pattern} is omitted all errors are caught.
6491 Examples: >
6492 :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C)
6493 :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors
6494 :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts
6495 :catch /^Vim(write):/ " catch all errors in :write
6496 :catch /^Vim\%((\a\+)\)\=:E123/ " catch error E123
6497 :catch /my-exception/ " catch user exception
6498 :catch /.*/ " catch everything
6499 :catch " same as /.*/
6500 <
6501 Another character can be used instead of / around the
6502 {pattern}, so long as it does not have a special
6503 meaning (e.g., '|' or '"') and doesn't occur inside
6504 {pattern}.
6505 NOTE: It is not reliable to ":catch" the TEXT of
6506 an error message because it may vary in different
6507 locales.
6509 *:fina* *:finally* *E606* *E607*
6510 :fina[lly] The following commands until the matching |:endtry|
6511 are executed whenever the part between the matching
6512 |:try| and the ":finally" is left: either by falling
6513 through to the ":finally" or by a |:continue|,
6514 |:break|, |:finish|, or |:return|, or by an error or
6515 interrupt or exception (see |:throw|).
6517 *:th* *:throw* *E608*
6518 :th[row] {expr1} The {expr1} is evaluated and thrown as an exception.
6519 If the ":throw" is used after a |:try| but before the
6520 first corresponding |:catch|, commands are skipped
6521 until the first ":catch" matching {expr1} is reached.
6522 If there is no such ":catch" or if the ":throw" is
6523 used after a ":catch" but before the |:finally|, the
6524 commands following the ":finally" (if present) up to
6525 the matching |:endtry| are executed. If the ":throw"
6526 is after the ":finally", commands up to the ":endtry"
6527 are skipped. At the ":endtry", this process applies
6528 again for the next dynamically surrounding ":try"
6529 (which may be found in a calling function or sourcing
6530 script), until a matching ":catch" has been found.
6531 If the exception is not caught, the command processing
6532 is terminated.
6533 Example: >
6534 :try | throw "oops" | catch /^oo/ | echo "caught" | endtry
6535 <
6537 *:ec* *:echo*
6538 :ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The
6539 first {expr1} starts on a new line.
6540 Also see |:comment|.
6541 Use "\n" to start a new line. Use "\r" to move the
6542 cursor to the first column.
6543 Uses the highlighting set by the |:echohl| command.
6544 Cannot be followed by a comment.
6545 Example: >
6546 :echo "the value of 'shell' is" &shell
6547 < *:echo-redraw*
6548 A later redraw may make the message disappear again.
6549 And since Vim mostly postpones redrawing until it's
6550 finished with a sequence of commands this happens
6551 quite often. To avoid that a command from before the
6552 ":echo" causes a redraw afterwards (redraws are often
6553 postponed until you type something), force a redraw
6554 with the |:redraw| command. Example: >
6555 :new | redraw | echo "there is a new window"
6556 <
6557 *:echon*
6558 :echon {expr1} .. Echoes each {expr1}, without anything added. Also see
6559 |:comment|.
6560 Uses the highlighting set by the |:echohl| command.
6561 Cannot be followed by a comment.
6562 Example: >
6563 :echon "the value of 'shell' is " &shell
6564 <
6565 Note the difference between using ":echo", which is a
6566 Vim command, and ":!echo", which is an external shell
6567 command: >
6568 :!echo % --> filename
6569 < The arguments of ":!" are expanded, see |:_%|. >
6570 :!echo "%" --> filename or "filename"
6571 < Like the previous example. Whether you see the double
6572 quotes or not depends on your 'shell'. >
6573 :echo % --> nothing
6574 < The '%' is an illegal character in an expression. >
6575 :echo "%" --> %
6576 < This just echoes the '%' character. >
6577 :echo expand("%") --> filename
6578 < This calls the expand() function to expand the '%'.
6580 *:echoh* *:echohl*
6581 :echoh[l] {name} Use the highlight group {name} for the following
6582 |:echo|, |:echon| and |:echomsg| commands. Also used
6583 for the |input()| prompt. Example: >
6584 :echohl WarningMsg | echo "Don't panic!" | echohl None
6585 < Don't forget to set the group back to "None",
6586 otherwise all following echo's will be highlighted.
6588 *:echom* *:echomsg*
6589 :echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the
6590 message in the |message-history|.
6591 Spaces are placed between the arguments as with the
6592 |:echo| command. But unprintable characters are
6593 displayed, not interpreted.
6594 The parsing works slightly different from |:echo|,
6595 more like |:execute|. All the expressions are first
6596 evaluated and concatenated before echoing anything.
6597 The expressions must evaluate to a Number or String, a
6598 Dictionary or List causes an error.
6599 Uses the highlighting set by the |:echohl| command.
6600 Example: >
6601 :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."
6602 < See |:echo-redraw| to avoid the message disappearing
6603 when the screen is redrawn.
6604 *:echoe* *:echoerr*
6605 :echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the
6606 message in the |message-history|. When used in a
6607 script or function the line number will be added.
6608 Spaces are placed between the arguments as with the
6609 :echo command. When used inside a try conditional,
6610 the message is raised as an error exception instead
6611 (see |try-echoerr|).
6612 Example: >
6613 :echoerr "This script just failed!"
6614 < If you just want a highlighted message use |:echohl|.
6615 And to get a beep: >
6616 :exe "normal \<Esc>"
6617 <
6618 *:exe* *:execute*
6619 :exe[cute] {expr1} .. Executes the string that results from the evaluation
6620 of {expr1} as an Ex command. Multiple arguments are
6621 concatenated, with a space in between. {expr1} is
6622 used as the processed command, command line editing
6623 keys are not recognized.
6624 Cannot be followed by a comment.
6625 Examples: >
6626 :execute "buffer " nextbuf
6627 :execute "normal " count . "w"
6628 <
6629 ":execute" can be used to append a command to commands
6630 that don't accept a '|'. Example: >
6631 :execute '!ls' | echo "theend"
6633 < ":execute" is also a nice way to avoid having to type
6634 control characters in a Vim script for a ":normal"
6635 command: >
6636 :execute "normal ixxx\<Esc>"
6637 < This has an <Esc> character, see |expr-string|.
6639 Be careful to correctly escape special characters in
6640 file names. The |fnameescape()| function can be used
6641 for this. Example: >
6642 :execute "e " . fnameescape(filename)
6643 <
6644 Note: The executed string may be any command-line, but
6645 you cannot start or end a "while", "for" or "if"
6646 command. Thus this is illegal: >
6647 :execute 'while i > 5'
6648 :execute 'echo "test" | break'
6649 <
6650 It is allowed to have a "while" or "if" command
6651 completely in the executed string: >
6652 :execute 'while i < 5 | echo i | let i = i + 1 | endwhile'
6653 <
6655 *:comment*
6656 ":execute", ":echo" and ":echon" cannot be followed by
6657 a comment directly, because they see the '"' as the
6658 start of a string. But, you can use '|' followed by a
6659 comment. Example: >
6660 :echo "foo" | "this is a comment
6662 ==============================================================================
6663 8. Exception handling *exception-handling*
6665 The Vim script language comprises an exception handling feature. This section
6666 explains how it can be used in a Vim script.
6668 Exceptions may be raised by Vim on an error or on interrupt, see
6669 |catch-errors| and |catch-interrupt|. You can also explicitly throw an
6670 exception by using the ":throw" command, see |throw-catch|.
6673 TRY CONDITIONALS *try-conditionals*
6675 Exceptions can be caught or can cause cleanup code to be executed. You can
6676 use a try conditional to specify catch clauses (that catch exceptions) and/or
6677 a finally clause (to be executed for cleanup).
6678 A try conditional begins with a |:try| command and ends at the matching
6679 |:endtry| command. In between, you can use a |:catch| command to start
6680 a catch clause, or a |:finally| command to start a finally clause. There may
6681 be none or multiple catch clauses, but there is at most one finally clause,
6682 which must not be followed by any catch clauses. The lines before the catch
6683 clauses and the finally clause is called a try block. >
6685 :try
6686 : ...
6687 : ... TRY BLOCK
6688 : ...
6689 :catch /{pattern}/
6690 : ...
6691 : ... CATCH CLAUSE
6692 : ...
6693 :catch /{pattern}/
6694 : ...
6695 : ... CATCH CLAUSE
6696 : ...
6697 :finally
6698 : ...
6699 : ... FINALLY CLAUSE
6700 : ...
6701 :endtry
6703 The try conditional allows to watch code for exceptions and to take the
6704 appropriate actions. Exceptions from the try block may be caught. Exceptions
6705 from the try block and also the catch clauses may cause cleanup actions.
6706 When no exception is thrown during execution of the try block, the control
6707 is transferred to the finally clause, if present. After its execution, the
6708 script continues with the line following the ":endtry".
6709 When an exception occurs during execution of the try block, the remaining
6710 lines in the try block are skipped. The exception is matched against the
6711 patterns specified as arguments to the ":catch" commands. The catch clause
6712 after the first matching ":catch" is taken, other catch clauses are not
6713 executed. The catch clause ends when the next ":catch", ":finally", or
6714 ":endtry" command is reached - whatever is first. Then, the finally clause
6715 (if present) is executed. When the ":endtry" is reached, the script execution
6716 continues in the following line as usual.
6717 When an exception that does not match any of the patterns specified by the
6718 ":catch" commands is thrown in the try block, the exception is not caught by
6719 that try conditional and none of the catch clauses is executed. Only the
6720 finally clause, if present, is taken. The exception pends during execution of
6721 the finally clause. It is resumed at the ":endtry", so that commands after
6722 the ":endtry" are not executed and the exception might be caught elsewhere,
6723 see |try-nesting|.
6724 When during execution of a catch clause another exception is thrown, the
6725 remaining lines in that catch clause are not executed. The new exception is
6726 not matched against the patterns in any of the ":catch" commands of the same
6727 try conditional and none of its catch clauses is taken. If there is, however,
6728 a finally clause, it is executed, and the exception pends during its
6729 execution. The commands following the ":endtry" are not executed. The new
6730 exception might, however, be caught elsewhere, see |try-nesting|.
6731 When during execution of the finally clause (if present) an exception is
6732 thrown, the remaining lines in the finally clause are skipped. If the finally
6733 clause has been taken because of an exception from the try block or one of the
6734 catch clauses, the original (pending) exception is discarded. The commands
6735 following the ":endtry" are not executed, and the exception from the finally
6736 clause is propagated and can be caught elsewhere, see |try-nesting|.
6738 The finally clause is also executed, when a ":break" or ":continue" for
6739 a ":while" loop enclosing the complete try conditional is executed from the
6740 try block or a catch clause. Or when a ":return" or ":finish" is executed
6741 from the try block or a catch clause of a try conditional in a function or
6742 sourced script, respectively. The ":break", ":continue", ":return", or
6743 ":finish" pends during execution of the finally clause and is resumed when the
6744 ":endtry" is reached. It is, however, discarded when an exception is thrown
6745 from the finally clause.
6746 When a ":break" or ":continue" for a ":while" loop enclosing the complete
6747 try conditional or when a ":return" or ":finish" is encountered in the finally
6748 clause, the rest of the finally clause is skipped, and the ":break",
6749 ":continue", ":return" or ":finish" is executed as usual. If the finally
6750 clause has been taken because of an exception or an earlier ":break",
6751 ":continue", ":return", or ":finish" from the try block or a catch clause,
6752 this pending exception or command is discarded.
6754 For examples see |throw-catch| and |try-finally|.
6757 NESTING OF TRY CONDITIONALS *try-nesting*
6759 Try conditionals can be nested arbitrarily. That is, a complete try
6760 conditional can be put into the try block, a catch clause, or the finally
6761 clause of another try conditional. If the inner try conditional does not
6762 catch an exception thrown in its try block or throws a new exception from one
6763 of its catch clauses or its finally clause, the outer try conditional is
6764 checked according to the rules above. If the inner try conditional is in the
6765 try block of the outer try conditional, its catch clauses are checked, but
6766 otherwise only the finally clause is executed. It does not matter for
6767 nesting, whether the inner try conditional is directly contained in the outer
6768 one, or whether the outer one sources a script or calls a function containing
6769 the inner try conditional.
6771 When none of the active try conditionals catches an exception, just their
6772 finally clauses are executed. Thereafter, the script processing terminates.
6773 An error message is displayed in case of an uncaught exception explicitly
6774 thrown by a ":throw" command. For uncaught error and interrupt exceptions
6775 implicitly raised by Vim, the error message(s) or interrupt message are shown
6776 as usual.
6778 For examples see |throw-catch|.
6781 EXAMINING EXCEPTION HANDLING CODE *except-examine*
6783 Exception handling code can get tricky. If you are in doubt what happens, set
6784 'verbose' to 13 or use the ":13verbose" command modifier when sourcing your
6785 script file. Then you see when an exception is thrown, discarded, caught, or
6786 finished. When using a verbosity level of at least 14, things pending in
6787 a finally clause are also shown. This information is also given in debug mode
6788 (see |debug-scripts|).
6791 THROWING AND CATCHING EXCEPTIONS *throw-catch*
6793 You can throw any number or string as an exception. Use the |:throw| command
6794 and pass the value to be thrown as argument: >
6795 :throw 4711
6796 :throw "string"
6797 < *throw-expression*
6798 You can also specify an expression argument. The expression is then evaluated
6799 first, and the result is thrown: >
6800 :throw 4705 + strlen("string")
6801 :throw strpart("strings", 0, 6)
6803 An exception might be thrown during evaluation of the argument of the ":throw"
6804 command. Unless it is caught there, the expression evaluation is abandoned.
6805 The ":throw" command then does not throw a new exception.
6806 Example: >
6808 :function! Foo(arg)
6809 : try
6810 : throw a:arg
6811 : catch /foo/
6812 : endtry
6813 : return 1
6814 :endfunction
6815 :
6816 :function! Bar()
6817 : echo "in Bar"
6818 : return 4710
6819 :endfunction
6820 :
6821 :throw Foo("arrgh") + Bar()
6823 This throws "arrgh", and "in Bar" is not displayed since Bar() is not
6824 executed. >
6825 :throw Foo("foo") + Bar()
6826 however displays "in Bar" and throws 4711.
6828 Any other command that takes an expression as argument might also be
6829 abandoned by an (uncaught) exception during the expression evaluation. The
6830 exception is then propagated to the caller of the command.
6831 Example: >
6833 :if Foo("arrgh")
6834 : echo "then"
6835 :else
6836 : echo "else"
6837 :endif
6839 Here neither of "then" or "else" is displayed.
6841 *catch-order*
6842 Exceptions can be caught by a try conditional with one or more |:catch|
6843 commands, see |try-conditionals|. The values to be caught by each ":catch"
6844 command can be specified as a pattern argument. The subsequent catch clause
6845 gets executed when a matching exception is caught.
6846 Example: >
6848 :function! Foo(value)
6849 : try
6850 : throw a:value
6851 : catch /^\d\+$/
6852 : echo "Number thrown"
6853 : catch /.*/
6854 : echo "String thrown"
6855 : endtry
6856 :endfunction
6857 :
6858 :call Foo(0x1267)
6859 :call Foo('string')
6861 The first call to Foo() displays "Number thrown", the second "String thrown".
6862 An exception is matched against the ":catch" commands in the order they are
6863 specified. Only the first match counts. So you should place the more
6864 specific ":catch" first. The following order does not make sense: >
6866 : catch /.*/
6867 : echo "String thrown"
6868 : catch /^\d\+$/
6869 : echo "Number thrown"
6871 The first ":catch" here matches always, so that the second catch clause is
6872 never taken.
6874 *throw-variables*
6875 If you catch an exception by a general pattern, you may access the exact value
6876 in the variable |v:exception|: >
6878 : catch /^\d\+$/
6879 : echo "Number thrown. Value is" v:exception
6881 You may also be interested where an exception was thrown. This is stored in
6882 |v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the
6883 exception most recently caught as long it is not finished.
6884 Example: >
6886 :function! Caught()
6887 : if v:exception != ""
6888 : echo 'Caught "' . v:exception . '" in ' . v:throwpoint
6889 : else
6890 : echo 'Nothing caught'
6891 : endif
6892 :endfunction
6893 :
6894 :function! Foo()
6895 : try
6896 : try
6897 : try
6898 : throw 4711
6899 : finally
6900 : call Caught()
6901 : endtry
6902 : catch /.*/
6903 : call Caught()
6904 : throw "oops"
6905 : endtry
6906 : catch /.*/
6907 : call Caught()
6908 : finally
6909 : call Caught()
6910 : endtry
6911 :endfunction
6912 :
6913 :call Foo()
6915 This displays >
6917 Nothing caught
6918 Caught "4711" in function Foo, line 4
6919 Caught "oops" in function Foo, line 10
6920 Nothing caught
6922 A practical example: The following command ":LineNumber" displays the line
6923 number in the script or function where it has been used: >
6925 :function! LineNumber()
6926 : return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")
6927 :endfunction
6928 :command! LineNumber try | throw "" | catch | echo LineNumber() | endtry
6929 <
6930 *try-nested*
6931 An exception that is not caught by a try conditional can be caught by
6932 a surrounding try conditional: >
6934 :try
6935 : try
6936 : throw "foo"
6937 : catch /foobar/
6938 : echo "foobar"
6939 : finally
6940 : echo "inner finally"
6941 : endtry
6942 :catch /foo/
6943 : echo "foo"
6944 :endtry
6946 The inner try conditional does not catch the exception, just its finally
6947 clause is executed. The exception is then caught by the outer try
6948 conditional. The example displays "inner finally" and then "foo".
6950 *throw-from-catch*
6951 You can catch an exception and throw a new one to be caught elsewhere from the
6952 catch clause: >
6954 :function! Foo()
6955 : throw "foo"
6956 :endfunction
6957 :
6958 :function! Bar()
6959 : try
6960 : call Foo()
6961 : catch /foo/
6962 : echo "Caught foo, throw bar"
6963 : throw "bar"
6964 : endtry
6965 :endfunction
6966 :
6967 :try
6968 : call Bar()
6969 :catch /.*/
6970 : echo "Caught" v:exception
6971 :endtry
6973 This displays "Caught foo, throw bar" and then "Caught bar".
6975 *rethrow*
6976 There is no real rethrow in the Vim script language, but you may throw
6977 "v:exception" instead: >
6979 :function! Bar()
6980 : try
6981 : call Foo()
6982 : catch /.*/
6983 : echo "Rethrow" v:exception
6984 : throw v:exception
6985 : endtry
6986 :endfunction
6987 < *try-echoerr*
6988 Note that this method cannot be used to "rethrow" Vim error or interrupt
6989 exceptions, because it is not possible to fake Vim internal exceptions.
6990 Trying so causes an error exception. You should throw your own exception
6991 denoting the situation. If you want to cause a Vim error exception containing
6992 the original error exception value, you can use the |:echoerr| command: >
6994 :try
6995 : try
6996 : asdf
6997 : catch /.*/
6998 : echoerr v:exception
6999 : endtry
7000 :catch /.*/
7001 : echo v:exception
7002 :endtry
7004 This code displays
7006 Vim(echoerr):Vim:E492: Not an editor command: asdf ~
7009 CLEANUP CODE *try-finally*
7011 Scripts often change global settings and restore them at their end. If the
7012 user however interrupts the script by pressing CTRL-C, the settings remain in
7013 an inconsistent state. The same may happen to you in the development phase of
7014 a script when an error occurs or you explicitly throw an exception without
7015 catching it. You can solve these problems by using a try conditional with
7016 a finally clause for restoring the settings. Its execution is guaranteed on
7017 normal control flow, on error, on an explicit ":throw", and on interrupt.
7018 (Note that errors and interrupts from inside the try conditional are converted
7019 to exceptions. When not caught, they terminate the script after the finally
7020 clause has been executed.)
7021 Example: >
7023 :try
7024 : let s:saved_ts = &ts
7025 : set ts=17
7026 :
7027 : " Do the hard work here.
7028 :
7029 :finally
7030 : let &ts = s:saved_ts
7031 : unlet s:saved_ts
7032 :endtry
7034 This method should be used locally whenever a function or part of a script
7035 changes global settings which need to be restored on failure or normal exit of
7036 that function or script part.
7038 *break-finally*
7039 Cleanup code works also when the try block or a catch clause is left by
7040 a ":continue", ":break", ":return", or ":finish".
7041 Example: >
7043 :let first = 1
7044 :while 1
7045 : try
7046 : if first
7047 : echo "first"
7048 : let first = 0
7049 : continue
7050 : else
7051 : throw "second"
7052 : endif
7053 : catch /.*/
7054 : echo v:exception
7055 : break
7056 : finally
7057 : echo "cleanup"
7058 : endtry
7059 : echo "still in while"
7060 :endwhile
7061 :echo "end"
7063 This displays "first", "cleanup", "second", "cleanup", and "end". >
7065 :function! Foo()
7066 : try
7067 : return 4711
7068 : finally
7069 : echo "cleanup\n"
7070 : endtry
7071 : echo "Foo still active"
7072 :endfunction
7073 :
7074 :echo Foo() "returned by Foo"
7076 This displays "cleanup" and "4711 returned by Foo". You don't need to add an
7077 extra ":return" in the finally clause. (Above all, this would override the
7078 return value.)
7080 *except-from-finally*
7081 Using either of ":continue", ":break", ":return", ":finish", or ":throw" in
7082 a finally clause is possible, but not recommended since it abandons the
7083 cleanup actions for the try conditional. But, of course, interrupt and error
7084 exceptions might get raised from a finally clause.
7085 Example where an error in the finally clause stops an interrupt from
7086 working correctly: >
7088 :try
7089 : try
7090 : echo "Press CTRL-C for interrupt"
7091 : while 1
7092 : endwhile
7093 : finally
7094 : unlet novar
7095 : endtry
7096 :catch /novar/
7097 :endtry
7098 :echo "Script still running"
7099 :sleep 1
7101 If you need to put commands that could fail into a finally clause, you should
7102 think about catching or ignoring the errors in these commands, see
7103 |catch-errors| and |ignore-errors|.
7106 CATCHING ERRORS *catch-errors*
7108 If you want to catch specific errors, you just have to put the code to be
7109 watched in a try block and add a catch clause for the error message. The
7110 presence of the try conditional causes all errors to be converted to an
7111 exception. No message is displayed and |v:errmsg| is not set then. To find
7112 the right pattern for the ":catch" command, you have to know how the format of
7113 the error exception is.
7114 Error exceptions have the following format: >
7116 Vim({cmdname}):{errmsg}
7117 or >
7118 Vim:{errmsg}
7120 {cmdname} is the name of the command that failed; the second form is used when
7121 the command name is not known. {errmsg} is the error message usually produced
7122 when the error occurs outside try conditionals. It always begins with
7123 a capital "E", followed by a two or three-digit error number, a colon, and
7124 a space.
7126 Examples:
7128 The command >
7129 :unlet novar
7130 normally produces the error message >
7131 E108: No such variable: "novar"
7132 which is converted inside try conditionals to an exception >
7133 Vim(unlet):E108: No such variable: "novar"
7135 The command >
7136 :dwim
7137 normally produces the error message >
7138 E492: Not an editor command: dwim
7139 which is converted inside try conditionals to an exception >
7140 Vim:E492: Not an editor command: dwim
7142 You can catch all ":unlet" errors by a >
7143 :catch /^Vim(unlet):/
7144 or all errors for misspelled command names by a >
7145 :catch /^Vim:E492:/
7147 Some error messages may be produced by different commands: >
7148 :function nofunc
7149 and >
7150 :delfunction nofunc
7151 both produce the error message >
7152 E128: Function name must start with a capital: nofunc
7153 which is converted inside try conditionals to an exception >
7154 Vim(function):E128: Function name must start with a capital: nofunc
7155 or >
7156 Vim(delfunction):E128: Function name must start with a capital: nofunc
7157 respectively. You can catch the error by its number independently on the
7158 command that caused it if you use the following pattern: >
7159 :catch /^Vim(\a\+):E128:/
7161 Some commands like >
7162 :let x = novar
7163 produce multiple error messages, here: >
7164 E121: Undefined variable: novar
7165 E15: Invalid expression: novar
7166 Only the first is used for the exception value, since it is the most specific
7167 one (see |except-several-errors|). So you can catch it by >
7168 :catch /^Vim(\a\+):E121:/
7170 You can catch all errors related to the name "nofunc" by >
7171 :catch /\<nofunc\>/
7173 You can catch all Vim errors in the ":write" and ":read" commands by >
7174 :catch /^Vim(\(write\|read\)):E\d\+:/
7176 You can catch all Vim errors by the pattern >
7177 :catch /^Vim\((\a\+)\)\=:E\d\+:/
7178 <
7179 *catch-text*
7180 NOTE: You should never catch the error message text itself: >
7181 :catch /No such variable/
7182 only works in the english locale, but not when the user has selected
7183 a different language by the |:language| command. It is however helpful to
7184 cite the message text in a comment: >
7185 :catch /^Vim(\a\+):E108:/ " No such variable
7188 IGNORING ERRORS *ignore-errors*
7190 You can ignore errors in a specific Vim command by catching them locally: >
7192 :try
7193 : write
7194 :catch
7195 :endtry
7197 But you are strongly recommended NOT to use this simple form, since it could
7198 catch more than you want. With the ":write" command, some autocommands could
7199 be executed and cause errors not related to writing, for instance: >
7201 :au BufWritePre * unlet novar
7203 There could even be such errors you are not responsible for as a script
7204 writer: a user of your script might have defined such autocommands. You would
7205 then hide the error from the user.
7206 It is much better to use >
7208 :try
7209 : write
7210 :catch /^Vim(write):/
7211 :endtry
7213 which only catches real write errors. So catch only what you'd like to ignore
7214 intentionally.
7216 For a single command that does not cause execution of autocommands, you could
7217 even suppress the conversion of errors to exceptions by the ":silent!"
7218 command: >
7219 :silent! nunmap k
7220 This works also when a try conditional is active.
7223 CATCHING INTERRUPTS *catch-interrupt*
7225 When there are active try conditionals, an interrupt (CTRL-C) is converted to
7226 the exception "Vim:Interrupt". You can catch it like every exception. The
7227 script is not terminated, then.
7228 Example: >
7230 :function! TASK1()
7231 : sleep 10
7232 :endfunction
7234 :function! TASK2()
7235 : sleep 20
7236 :endfunction
7238 :while 1
7239 : let command = input("Type a command: ")
7240 : try
7241 : if command == ""
7242 : continue
7243 : elseif command == "END"
7244 : break
7245 : elseif command == "TASK1"
7246 : call TASK1()
7247 : elseif command == "TASK2"
7248 : call TASK2()
7249 : else
7250 : echo "\nIllegal command:" command
7251 : continue
7252 : endif
7253 : catch /^Vim:Interrupt$/
7254 : echo "\nCommand interrupted"
7255 : " Caught the interrupt. Continue with next prompt.
7256 : endtry
7257 :endwhile
7259 You can interrupt a task here by pressing CTRL-C; the script then asks for
7260 a new command. If you press CTRL-C at the prompt, the script is terminated.
7262 For testing what happens when CTRL-C would be pressed on a specific line in
7263 your script, use the debug mode and execute the |>quit| or |>interrupt|
7264 command on that line. See |debug-scripts|.
7267 CATCHING ALL *catch-all*
7269 The commands >
7271 :catch /.*/
7272 :catch //
7273 :catch
7275 catch everything, error exceptions, interrupt exceptions and exceptions
7276 explicitly thrown by the |:throw| command. This is useful at the top level of
7277 a script in order to catch unexpected things.
7278 Example: >
7280 :try
7281 :
7282 : " do the hard work here
7283 :
7284 :catch /MyException/
7285 :
7286 : " handle known problem
7287 :
7288 :catch /^Vim:Interrupt$/
7289 : echo "Script interrupted"
7290 :catch /.*/
7291 : echo "Internal error (" . v:exception . ")"
7292 : echo " - occurred at " . v:throwpoint
7293 :endtry
7294 :" end of script
7296 Note: Catching all might catch more things than you want. Thus, you are
7297 strongly encouraged to catch only for problems that you can really handle by
7298 specifying a pattern argument to the ":catch".
7299 Example: Catching all could make it nearly impossible to interrupt a script
7300 by pressing CTRL-C: >
7302 :while 1
7303 : try
7304 : sleep 1
7305 : catch
7306 : endtry
7307 :endwhile
7310 EXCEPTIONS AND AUTOCOMMANDS *except-autocmd*
7312 Exceptions may be used during execution of autocommands. Example: >
7314 :autocmd User x try
7315 :autocmd User x throw "Oops!"
7316 :autocmd User x catch
7317 :autocmd User x echo v:exception
7318 :autocmd User x endtry
7319 :autocmd User x throw "Arrgh!"
7320 :autocmd User x echo "Should not be displayed"
7321 :
7322 :try
7323 : doautocmd User x
7324 :catch
7325 : echo v:exception
7326 :endtry
7328 This displays "Oops!" and "Arrgh!".
7330 *except-autocmd-Pre*
7331 For some commands, autocommands get executed before the main action of the
7332 command takes place. If an exception is thrown and not caught in the sequence
7333 of autocommands, the sequence and the command that caused its execution are
7334 abandoned and the exception is propagated to the caller of the command.
7335 Example: >
7337 :autocmd BufWritePre * throw "FAIL"
7338 :autocmd BufWritePre * echo "Should not be displayed"
7339 :
7340 :try
7341 : write
7342 :catch
7343 : echo "Caught:" v:exception "from" v:throwpoint
7344 :endtry
7346 Here, the ":write" command does not write the file currently being edited (as
7347 you can see by checking 'modified'), since the exception from the BufWritePre
7348 autocommand abandons the ":write". The exception is then caught and the
7349 script displays: >
7351 Caught: FAIL from BufWrite Auto commands for "*"
7352 <
7353 *except-autocmd-Post*
7354 For some commands, autocommands get executed after the main action of the
7355 command has taken place. If this main action fails and the command is inside
7356 an active try conditional, the autocommands are skipped and an error exception
7357 is thrown that can be caught by the caller of the command.
7358 Example: >
7360 :autocmd BufWritePost * echo "File successfully written!"
7361 :
7362 :try
7363 : write /i/m/p/o/s/s/i/b/l/e
7364 :catch
7365 : echo v:exception
7366 :endtry
7368 This just displays: >
7370 Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)
7372 If you really need to execute the autocommands even when the main action
7373 fails, trigger the event from the catch clause.
7374 Example: >
7376 :autocmd BufWritePre * set noreadonly
7377 :autocmd BufWritePost * set readonly
7378 :
7379 :try
7380 : write /i/m/p/o/s/s/i/b/l/e
7381 :catch
7382 : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e
7383 :endtry
7384 <
7385 You can also use ":silent!": >
7387 :let x = "ok"
7388 :let v:errmsg = ""
7389 :autocmd BufWritePost * if v:errmsg != ""
7390 :autocmd BufWritePost * let x = "after fail"
7391 :autocmd BufWritePost * endif
7392 :try
7393 : silent! write /i/m/p/o/s/s/i/b/l/e
7394 :catch
7395 :endtry
7396 :echo x
7398 This displays "after fail".
7400 If the main action of the command does not fail, exceptions from the
7401 autocommands will be catchable by the caller of the command: >
7403 :autocmd BufWritePost * throw ":-("
7404 :autocmd BufWritePost * echo "Should not be displayed"
7405 :
7406 :try
7407 : write
7408 :catch
7409 : echo v:exception
7410 :endtry
7411 <
7412 *except-autocmd-Cmd*
7413 For some commands, the normal action can be replaced by a sequence of
7414 autocommands. Exceptions from that sequence will be catchable by the caller
7415 of the command.
7416 Example: For the ":write" command, the caller cannot know whether the file
7417 had actually been written when the exception occurred. You need to tell it in
7418 some way. >
7420 :if !exists("cnt")
7421 : let cnt = 0
7422 :
7423 : autocmd BufWriteCmd * if &modified
7424 : autocmd BufWriteCmd * let cnt = cnt + 1
7425 : autocmd BufWriteCmd * if cnt % 3 == 2
7426 : autocmd BufWriteCmd * throw "BufWriteCmdError"
7427 : autocmd BufWriteCmd * endif
7428 : autocmd BufWriteCmd * write | set nomodified
7429 : autocmd BufWriteCmd * if cnt % 3 == 0
7430 : autocmd BufWriteCmd * throw "BufWriteCmdError"
7431 : autocmd BufWriteCmd * endif
7432 : autocmd BufWriteCmd * echo "File successfully written!"
7433 : autocmd BufWriteCmd * endif
7434 :endif
7435 :
7436 :try
7437 : write
7438 :catch /^BufWriteCmdError$/
7439 : if &modified
7440 : echo "Error on writing (file contents not changed)"
7441 : else
7442 : echo "Error after writing"
7443 : endif
7444 :catch /^Vim(write):/
7445 : echo "Error on writing"
7446 :endtry
7448 When this script is sourced several times after making changes, it displays
7449 first >
7450 File successfully written!
7451 then >
7452 Error on writing (file contents not changed)
7453 then >
7454 Error after writing
7455 etc.
7457 *except-autocmd-ill*
7458 You cannot spread a try conditional over autocommands for different events.
7459 The following code is ill-formed: >
7461 :autocmd BufWritePre * try
7462 :
7463 :autocmd BufWritePost * catch
7464 :autocmd BufWritePost * echo v:exception
7465 :autocmd BufWritePost * endtry
7466 :
7467 :write
7470 EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS *except-hier-param*
7472 Some programming languages allow to use hierarchies of exception classes or to
7473 pass additional information with the object of an exception class. You can do
7474 similar things in Vim.
7475 In order to throw an exception from a hierarchy, just throw the complete
7476 class name with the components separated by a colon, for instance throw the
7477 string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library.
7478 When you want to pass additional information with your exception class, add
7479 it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)"
7480 for an error when writing "myfile".
7481 With the appropriate patterns in the ":catch" command, you can catch for
7482 base classes or derived classes of your hierarchy. Additional information in
7483 parentheses can be cut out from |v:exception| with the ":substitute" command.
7484 Example: >
7486 :function! CheckRange(a, func)
7487 : if a:a < 0
7488 : throw "EXCEPT:MATHERR:RANGE(" . a:func . ")"
7489 : endif
7490 :endfunction
7491 :
7492 :function! Add(a, b)
7493 : call CheckRange(a:a, "Add")
7494 : call CheckRange(a:b, "Add")
7495 : let c = a:a + a:b
7496 : if c < 0
7497 : throw "EXCEPT:MATHERR:OVERFLOW"
7498 : endif
7499 : return c
7500 :endfunction
7501 :
7502 :function! Div(a, b)
7503 : call CheckRange(a:a, "Div")
7504 : call CheckRange(a:b, "Div")
7505 : if (a:b == 0)
7506 : throw "EXCEPT:MATHERR:ZERODIV"
7507 : endif
7508 : return a:a / a:b
7509 :endfunction
7510 :
7511 :function! Write(file)
7512 : try
7513 : execute "write" fnameescape(a:file)
7514 : catch /^Vim(write):/
7515 : throw "EXCEPT:IO(" . getcwd() . ", " . a:file . "):WRITEERR"
7516 : endtry
7517 :endfunction
7518 :
7519 :try
7520 :
7521 : " something with arithmetics and I/O
7522 :
7523 :catch /^EXCEPT:MATHERR:RANGE/
7524 : let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "")
7525 : echo "Range error in" function
7526 :
7527 :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV
7528 : echo "Math error"
7529 :
7530 :catch /^EXCEPT:IO/
7531 : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "")
7532 : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "")
7533 : if file !~ '^/'
7534 : let file = dir . "/" . file
7535 : endif
7536 : echo 'I/O error for "' . file . '"'
7537 :
7538 :catch /^EXCEPT/
7539 : echo "Unspecified error"
7540 :
7541 :endtry
7543 The exceptions raised by Vim itself (on error or when pressing CTRL-C) use
7544 a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself
7545 exceptions with the "Vim" prefix; they are reserved for Vim.
7546 Vim error exceptions are parameterized with the name of the command that
7547 failed, if known. See |catch-errors|.
7550 PECULIARITIES
7551 *except-compat*
7552 The exception handling concept requires that the command sequence causing the
7553 exception is aborted immediately and control is transferred to finally clauses
7554 and/or a catch clause.
7556 In the Vim script language there are cases where scripts and functions
7557 continue after an error: in functions without the "abort" flag or in a command
7558 after ":silent!", control flow goes to the following line, and outside
7559 functions, control flow goes to the line following the outermost ":endwhile"
7560 or ":endif". On the other hand, errors should be catchable as exceptions
7561 (thus, requiring the immediate abortion).
7563 This problem has been solved by converting errors to exceptions and using
7564 immediate abortion (if not suppressed by ":silent!") only when a try
7565 conditional is active. This is no restriction since an (error) exception can
7566 be caught only from an active try conditional. If you want an immediate
7567 termination without catching the error, just use a try conditional without
7568 catch clause. (You can cause cleanup code being executed before termination
7569 by specifying a finally clause.)
7571 When no try conditional is active, the usual abortion and continuation
7572 behavior is used instead of immediate abortion. This ensures compatibility of
7573 scripts written for Vim 6.1 and earlier.
7575 However, when sourcing an existing script that does not use exception handling
7576 commands (or when calling one of its functions) from inside an active try
7577 conditional of a new script, you might change the control flow of the existing
7578 script on error. You get the immediate abortion on error and can catch the
7579 error in the new script. If however the sourced script suppresses error
7580 messages by using the ":silent!" command (checking for errors by testing
7581 |v:errmsg| if appropriate), its execution path is not changed. The error is
7582 not converted to an exception. (See |:silent|.) So the only remaining cause
7583 where this happens is for scripts that don't care about errors and produce
7584 error messages. You probably won't want to use such code from your new
7585 scripts.
7587 *except-syntax-err*
7588 Syntax errors in the exception handling commands are never caught by any of
7589 the ":catch" commands of the try conditional they belong to. Its finally
7590 clauses, however, is executed.
7591 Example: >
7593 :try
7594 : try
7595 : throw 4711
7596 : catch /\(/
7597 : echo "in catch with syntax error"
7598 : catch
7599 : echo "inner catch-all"
7600 : finally
7601 : echo "inner finally"
7602 : endtry
7603 :catch
7604 : echo 'outer catch-all caught "' . v:exception . '"'
7605 : finally
7606 : echo "outer finally"
7607 :endtry
7609 This displays: >
7610 inner finally
7611 outer catch-all caught "Vim(catch):E54: Unmatched \("
7612 outer finally
7613 The original exception is discarded and an error exception is raised, instead.
7615 *except-single-line*
7616 The ":try", ":catch", ":finally", and ":endtry" commands can be put on
7617 a single line, but then syntax errors may make it difficult to recognize the
7618 "catch" line, thus you better avoid this.
7619 Example: >
7620 :try | unlet! foo # | catch | endtry
7621 raises an error exception for the trailing characters after the ":unlet!"
7622 argument, but does not see the ":catch" and ":endtry" commands, so that the
7623 error exception is discarded and the "E488: Trailing characters" message gets
7624 displayed.
7626 *except-several-errors*
7627 When several errors appear in a single command, the first error message is
7628 usually the most specific one and therefor converted to the error exception.
7629 Example: >
7630 echo novar
7631 causes >
7632 E121: Undefined variable: novar
7633 E15: Invalid expression: novar
7634 The value of the error exception inside try conditionals is: >
7635 Vim(echo):E121: Undefined variable: novar
7636 < *except-syntax-error*
7637 But when a syntax error is detected after a normal error in the same command,
7638 the syntax error is used for the exception being thrown.
7639 Example: >
7640 unlet novar #
7641 causes >
7642 E108: No such variable: "novar"
7643 E488: Trailing characters
7644 The value of the error exception inside try conditionals is: >
7645 Vim(unlet):E488: Trailing characters
7646 This is done because the syntax error might change the execution path in a way
7647 not intended by the user. Example: >
7648 try
7649 try | unlet novar # | catch | echo v:exception | endtry
7650 catch /.*/
7651 echo "outer catch:" v:exception
7652 endtry
7653 This displays "outer catch: Vim(unlet):E488: Trailing characters", and then
7654 a "E600: Missing :endtry" error message is given, see |except-single-line|.
7656 ==============================================================================
7657 9. Examples *eval-examples*
7659 Printing in Binary ~
7660 >
7661 :" The function Nr2Bin() returns the Hex string of a number.
7662 :func Nr2Bin(nr)
7663 : let n = a:nr
7664 : let r = ""
7665 : while n
7666 : let r = '01'[n % 2] . r
7667 : let n = n / 2
7668 : endwhile
7669 : return r
7670 :endfunc
7672 :" The function String2Bin() converts each character in a string to a
7673 :" binary string, separated with dashes.
7674 :func String2Bin(str)
7675 : let out = ''
7676 : for ix in range(strlen(a:str))
7677 : let out = out . '-' . Nr2Bin(char2nr(a:str[ix]))
7678 : endfor
7679 : return out[1:]
7680 :endfunc
7682 Example of its use: >
7683 :echo Nr2Bin(32)
7684 result: "100000" >
7685 :echo String2Bin("32")
7686 result: "110011-110010"
7689 Sorting lines ~
7691 This example sorts lines with a specific compare function. >
7693 :func SortBuffer()
7694 : let lines = getline(1, '$')
7695 : call sort(lines, function("Strcmp"))
7696 : call setline(1, lines)
7697 :endfunction
7699 As a one-liner: >
7700 :call setline(1, sort(getline(1, '$'), function("Strcmp")))
7703 scanf() replacement ~
7704 *sscanf*
7705 There is no sscanf() function in Vim. If you need to extract parts from a
7706 line, you can use matchstr() and substitute() to do it. This example shows
7707 how to get the file name, line number and column number out of a line like
7708 "foobar.txt, 123, 45". >
7709 :" Set up the match bit
7710 :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)'
7711 :"get the part matching the whole expression
7712 :let l = matchstr(line, mx)
7713 :"get each item out of the match
7714 :let file = substitute(l, mx, '\1', '')
7715 :let lnum = substitute(l, mx, '\2', '')
7716 :let col = substitute(l, mx, '\3', '')
7718 The input is in the variable "line", the results in the variables "file",
7719 "lnum" and "col". (idea from Michael Geddes)
7722 getting the scriptnames in a Dictionary ~
7723 *scriptnames-dictionary*
7724 The |:scriptnames| command can be used to get a list of all script files that
7725 have been sourced. There is no equivalent function or variable for this
7726 (because it's rarely needed). In case you need to manipulate the list this
7727 code can be used: >
7728 " Get the output of ":scriptnames" in the scriptnames_output variable.
7729 let scriptnames_output = ''
7730 redir => scriptnames_output
7731 silent scriptnames
7732 redir END
7734 " Split the output into lines and parse each line. Add an entry to the
7735 " "scripts" dictionary.
7736 let scripts = {}
7737 for line in split(scriptnames_output, "\n")
7738 " Only do non-blank lines.
7739 if line =~ '\S'
7740 " Get the first number in the line.
7741 let nr = matchstr(line, '\d\+')
7742 " Get the file name, remove the script number " 123: ".
7743 let name = substitute(line, '.\+:\s*', '', '')
7744 " Add an item to the Dictionary
7745 let scripts[nr] = name
7746 endif
7747 endfor
7748 unlet scriptnames_output
7750 ==============================================================================
7751 10. No +eval feature *no-eval-feature*
7753 When the |+eval| feature was disabled at compile time, none of the expression
7754 evaluation commands are available. To prevent this from causing Vim scripts
7755 to generate all kinds of errors, the ":if" and ":endif" commands are still
7756 recognized, though the argument of the ":if" and everything between the ":if"
7757 and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but
7758 only if the commands are at the start of the line. The ":else" command is not
7759 recognized.
7761 Example of how to avoid executing commands when the |+eval| feature is
7762 missing: >
7764 :if 1
7765 : echo "Expression evaluation is compiled in"
7766 :else
7767 : echo "You will _never_ see this message"
7768 :endif
7770 ==============================================================================
7771 11. The sandbox *eval-sandbox* *sandbox* *E48*
7773 The 'foldexpr', 'includeexpr', 'indentexpr', 'statusline' and 'foldtext'
7774 options are evaluated in a sandbox. This means that you are protected from
7775 these expressions having nasty side effects. This gives some safety for when
7776 these options are set from a modeline. It is also used when the command from
7777 a tags file is executed and for CTRL-R = in the command line.
7778 The sandbox is also used for the |:sandbox| command.
7780 These items are not allowed in the sandbox:
7781 - changing the buffer text
7782 - defining or changing mapping, autocommands, functions, user commands
7783 - setting certain options (see |option-summary|)
7784 - setting certain v: variables (see |v:var|) *E794*
7785 - executing a shell command
7786 - reading or writing a file
7787 - jumping to another buffer or editing a file
7788 - executing Python, Perl, etc. commands
7789 This is not guaranteed 100% secure, but it should block most attacks.
7791 *:san* *:sandbox*
7792 :san[dbox] {cmd} Execute {cmd} in the sandbox. Useful to evaluate an
7793 option that may have been set from a modeline, e.g.
7794 'foldexpr'.
7796 *sandbox-option*
7797 A few options contain an expression. When this expression is evaluated it may
7798 have to be done in the sandbox to avoid a security risk. But the sandbox is
7799 restrictive, thus this only happens when the option was set from an insecure
7800 location. Insecure in this context are:
7801 - sourcing a .vimrc or .exrc in the current directory
7802 - while executing in the sandbox
7803 - value coming from a modeline
7805 Note that when in the sandbox and saving an option value and restoring it, the
7806 option will still be marked as it was set in the sandbox.
7808 ==============================================================================
7809 12. Textlock *textlock*
7811 In a few situations it is not allowed to change the text in the buffer, jump
7812 to another window and some other things that might confuse or break what Vim
7813 is currently doing. This mostly applies to things that happen when Vim is
7814 actually doing something else. For example, evaluating the 'balloonexpr' may
7815 happen any moment the mouse cursor is resting at some position.
7817 This is not allowed when the textlock is active:
7818 - changing the buffer text
7819 - jumping to another buffer or window
7820 - editing another file
7821 - closing a window or quitting Vim
7822 - etc.
7825 vim:tw=78:ts=8:ft=help:norl: