1 *eval.txt* For Vim version 7.2. Last change: 2009 Jan 10
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
15 1. Variables |variables|
17 1.2 Function references |Funcref|
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*
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
60 Example: {'blue': "#0000ff", 'red': "#ff0000"}
62 The Number and String types are converted automatically, depending on how they
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: >
86 To avoid a leading zero to cause octal conversion, or for using a different
89 For boolean operators Numbers are used. Zero is FALSE, non-zero is TRUE.
91 Note that in the command >
93 "foo" is converted to 0, which means FALSE. To test for a non-empty string,
96 < *E745* *E728* *E703* *E729* *E730* *E731*
97 List, Dictionary and Funcref types are not automatically converted.
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* *sticky-type-checking*
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, as well are Float and Number. Consider this sequence of
110 :let l = 44 " changes type from String to Number
111 :let l = [1, 2, 3] " error! l is still a Number
112 :let l = 4.4 " changes type from Number to Float
113 :let l = "string" " error!
116 1.2 Function references ~
117 *Funcref* *E695* *E718*
118 A Funcref variable is obtained with the |function()| function. It can be used
119 in an expression in the place of a function name, before the parenthesis
120 around the arguments, to invoke the function it refers to. Example: >
122 :let Fn = function("MyFunc")
124 < *E704* *E705* *E707*
125 A Funcref variable must start with a capital, "s:", "w:", "t:" or "b:". You
126 cannot have both a Funcref variable and a function with the same name.
128 A special case is defining a function and directly assigning its Funcref to a
129 Dictionary entry. Example: >
130 :function dict.init() dict
134 The key of the Dictionary can start with a lower case letter. The actual
135 function name is not used here. Also see |numbered-function|.
137 A Funcref can also be used with the |:call| command: >
141 The name of the referenced function can be obtained with |string()|. >
142 :let func = string(Fn)
144 You can use |call()| to invoke a Funcref and use a list variable for the
146 :let r = call(Fn, mylist)
150 *List* *Lists* *E686*
151 A List is an ordered sequence of items. An item can be of any type. Items
152 can be accessed by their index number. Items can be added and removed at any
153 position in the sequence.
158 A List is created with a comma separated list of items in square brackets.
160 :let mylist = [1, two, 3, "four"]
163 An item can be any expression. Using a List for an item creates a
165 :let nestlist = [[11, 12], [21, 22], [31, 32]]
167 An extra comma after the last item is ignored.
172 An item in the List can be accessed by putting the index in square brackets
173 after the List. Indexes are zero-based, thus the first item has index zero. >
174 :let item = mylist[0] " get the first item: 1
175 :let item = mylist[2] " get the third item: 3
177 When the resulting item is a list this can be repeated: >
178 :let item = nestlist[0][1] " get the first list, second item: 12
180 A negative index is counted from the end. Index -1 refers to the last item in
181 the List, -2 to the last but one item, etc. >
182 :let last = mylist[-1] " get the last item: "four"
184 To avoid an error for an invalid index use the |get()| function. When an item
185 is not available it returns zero or the default value you specify: >
186 :echo get(mylist, idx)
187 :echo get(mylist, idx, "NONE")
192 Two lists can be concatenated with the "+" operator: >
193 :let longlist = mylist + [5, 6]
194 :let mylist += [7, 8]
196 To prepend or append an item turn the item into a list by putting [] around
197 it. To change a list in-place see |list-modification| below.
202 A part of the List can be obtained by specifying the first and last index,
203 separated by a colon in square brackets: >
204 :let shortlist = mylist[2:-1] " get List [3, "four"]
206 Omitting the first index is similar to zero. Omitting the last index is
208 :let endlist = mylist[2:] " from item 2 to the end: [3, "four"]
209 :let shortlist = mylist[2:2] " List with one item: [3]
210 :let otherlist = mylist[:] " make a copy of the List
212 If the first index is beyond the last item of the List or the second item is
213 before the first item, the result is an empty list. There is no error
216 If the second index is equal to or greater than the length of the list the
217 length minus one is used: >
218 :let mylist = [0, 1, 2, 3]
219 :echo mylist[2:8] " result: [2, 3]
221 NOTE: mylist[s:e] means using the variable "s:e" as index. Watch out for
222 using a single letter variable before the ":". Insert a space when needed:
228 When variable "aa" is a list and you assign it to another variable "bb", both
229 variables refer to the same list. Thus changing the list "aa" will also
237 Making a copy of a list is done with the |copy()| function. Using [:] also
238 works, as explained above. This creates a shallow copy of the list: Changing
239 a list item in the list will also change the item in the copied list: >
240 :let aa = [[1, 'a'], 2, 3]
243 :let aa[0][1] = 'aaa'
245 < [[1, aaa], 2, 3, 4] >
249 To make a completely independent list use |deepcopy()|. This also makes a
250 copy of the values in the list, recursively. Up to a hundred levels deep.
252 The operator "is" can be used to check if two variables refer to the same
253 List. "isnot" does the opposite. In contrast "==" compares if two lists have
255 :let alist = [1, 2, 3]
256 :let blist = [1, 2, 3]
262 Note about comparing lists: Two lists are considered equal if they have the
263 same length and all items compare equal, as with using "==". There is one
264 exception: When comparing a number with a string they are considered
265 different. There is no automatic type conversion, as with using "==" on
266 variables. Example: >
272 Thus comparing Lists is more strict than comparing numbers and strings. You
273 can compare simple values this way too by putting them in a list: >
285 To unpack the items in a list to individual variables, put the variables in
286 square brackets, like list items: >
287 :let [var1, var2] = mylist
289 When the number of variables does not match the number of items in the list
290 this produces an error. To handle any extra items from the list append ";"
291 and a variable name: >
292 :let [var1, var2; rest] = mylist
295 :let var1 = mylist[0]
296 :let var2 = mylist[1]
297 :let rest = mylist[2:]
299 Except that there is no error if there are only two items. "rest" will be an
305 To change a specific item of a list use |:let| this way: >
306 :let list[4] = "four"
307 :let listlist[0][3] = item
309 To change part of a list you can specify the first and last item to be
310 modified. The value must at least have the number of items in the range: >
311 :let list[3:5] = [3, 4, 5]
313 Adding and removing items from a list is done with functions. Here are a few
315 :call insert(list, 'a') " prepend item 'a'
316 :call insert(list, 'a', 3) " insert item 'a' before list[3]
317 :call add(list, "new") " append String item
318 :call add(list, [1, 2]) " append a List as one new item
319 :call extend(list, [1, 2]) " extend the list with two more items
320 :let i = remove(list, 3) " remove item 3
321 :unlet list[3] " idem
322 :let l = remove(list, 3, -1) " remove items 3 to last item
323 :unlet list[3 : ] " idem
324 :call filter(list, 'v:val !~ "x"') " remove items with an 'x'
326 Changing the order of items in a list: >
327 :call sort(list) " sort a list alphabetically
328 :call reverse(list) " reverse the order of items
333 The |:for| loop executes commands for each item in a list. A variable is set
334 to each item in the list in sequence. Example: >
341 :while index < len(mylist)
342 : let item = mylist[index]
344 : let index = index + 1
347 Note that all items in the list should be of the same type, otherwise this
348 results in error |E706|. To avoid this |:unlet| the variable at the end of
351 If all you want to do is modify each item in the list then the |map()|
352 function will be a simpler method than a for loop.
354 Just like the |:let| command, |:for| also accepts a list of variables. This
355 requires the argument to be a list of lists. >
356 :for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
357 : call Doit(lnum, col)
360 This works like a |:let| command is done for each list item. Again, the types
361 must remain the same to avoid an error.
363 It is also possible to put remaining items in a List variable: >
364 :for [i, j; rest] in listlist
367 : echo "remainder: " . string(rest)
374 Functions that are useful with a List: >
375 :let r = call(funcname, list) " call a function with an argument list
376 :if empty(list) " check if list is empty
377 :let l = len(list) " number of items in list
378 :let big = max(list) " maximum value in list
379 :let small = min(list) " minimum value in list
380 :let xs = count(list, 'x') " count nr of times 'x' appears in list
381 :let i = index(list, 'x') " index of first 'x' in list
382 :let lines = getline(1, 10) " get ten text lines from buffer
383 :call append('$', lines) " append text lines in buffer
384 :let list = split("a b c") " create list from items in a string
385 :let string = join(list, ', ') " create string from list items
386 :let s = string(list) " String representation of list
387 :call map(list, '">> " . v:val') " prepend ">> " to each item
389 Don't forget that a combination of features can make things simple. For
390 example, to add up all the numbers in a list: >
391 :exe 'let sum = ' . join(nrlist, '+')
395 *Dictionaries* *Dictionary*
396 A Dictionary is an associative array: Each entry has a key and a value. The
397 entry can be located with the key. The entries are stored without a specific
401 Dictionary creation ~
402 *E720* *E721* *E722* *E723*
403 A Dictionary is created with a comma separated list of entries in curly
404 braces. Each entry has a key and a value, separated by a colon. Each key can
405 only appear once. Examples: >
406 :let mydict = {1: 'one', 2: 'two', 3: 'three'}
408 < *E713* *E716* *E717*
409 A key is always a String. You can use a Number, it will be converted to a
410 String automatically. Thus the String '4' and the number 4 will find the same
411 entry. Note that the String '04' and the Number 04 are different, since the
412 Number will be converted to the String '4'.
414 A value can be any expression. Using a Dictionary for a value creates a
416 :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}}
418 An extra comma after the last entry is ignored.
423 The normal way to access an entry is by putting the key in square brackets: >
424 :let val = mydict["one"]
425 :let mydict["four"] = 4
427 You can add new entries to an existing Dictionary this way, unlike Lists.
429 For keys that consist entirely of letters, digits and underscore the following
430 form can be used |expr-entry|: >
431 :let val = mydict.one
434 Since an entry can be any type, also a List and a Dictionary, the indexing and
435 key lookup can be repeated: >
436 :echo dict.key[idx].key
439 Dictionary to List conversion ~
441 You may want to loop over the entries in a dictionary. For this you need to
442 turn the Dictionary into a List and pass it to |:for|.
444 Most often you want to loop over the keys, using the |keys()| function: >
445 :for key in keys(mydict)
446 : echo key . ': ' . mydict[key]
449 The List of keys is unsorted. You may want to sort them first: >
450 :for key in sort(keys(mydict))
452 To loop over the values use the |values()| function: >
453 :for v in values(mydict)
457 If you want both the key and the value use the |items()| function. It returns
458 a List in which each item is a List with two items, the key and the value: >
459 :for [key, value] in items(mydict)
460 : echo key . ': ' . value
464 Dictionary identity ~
466 Just like Lists you need to use |copy()| and |deepcopy()| to make a copy of a
467 Dictionary. Otherwise, assignment results in referring to the same
469 :let onedict = {'a': 1, 'b': 2}
475 Two Dictionaries compare equal if all the key-value pairs compare equal. For
476 more info see |list-identity|.
479 Dictionary modification ~
481 To change an already existing entry of a Dictionary, or to add a new entry,
482 use |:let| this way: >
483 :let dict[4] = "four"
484 :let dict['one'] = item
486 Removing an entry from a Dictionary is done with |remove()| or |:unlet|.
487 Three ways to remove the entry with key "aaa" from dict: >
488 :let i = remove(dict, 'aaa')
492 Merging a Dictionary with another is done with |extend()|: >
493 :call extend(adict, bdict)
494 This extends adict with all entries from bdict. Duplicate keys cause entries
495 in adict to be overwritten. An optional third argument can change this.
496 Note that the order of entries in a Dictionary is irrelevant, thus don't
497 expect ":echo adict" to show the items from bdict after the older entries in
500 Weeding out entries from a Dictionary can be done with |filter()|: >
501 :call filter(dict, 'v:val =~ "x"')
502 This removes all entries from "dict" with a value not matching 'x'.
505 Dictionary function ~
506 *Dictionary-function* *self* *E725*
507 When a function is defined with the "dict" attribute it can be used in a
508 special way with a dictionary. Example: >
509 :function Mylen() dict
510 : return len(self.data)
512 :let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}
515 This is like a method in object oriented programming. The entry in the
516 Dictionary is a |Funcref|. The local variable "self" refers to the dictionary
517 the function was invoked from.
519 It is also possible to add a function without the "dict" attribute as a
520 Funcref to a Dictionary, but the "self" variable is not available then.
522 *numbered-function* *anonymous-function*
523 To avoid the extra name for the function it can be defined and directly
524 assigned to a Dictionary in this way: >
525 :let mydict = {'data': [0, 1, 2, 3]}
526 :function mydict.len() dict
527 : return len(self.data)
531 The function will then get a number and the value of dict.len is a |Funcref|
532 that references this function. The function can only be used through a
533 |Funcref|. It will automatically be deleted when there is no |Funcref|
534 remaining that refers to it.
536 It is not necessary to use the "dict" attribute for a numbered function.
539 Functions for Dictionaries ~
541 Functions that can be used with a Dictionary: >
542 :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo"
543 :if empty(dict) " TRUE if dict is empty
544 :let l = len(dict) " number of items in dict
545 :let big = max(dict) " maximum value in dict
546 :let small = min(dict) " minimum value in dict
547 :let xs = count(dict, 'x') " count nr of times 'x' appears in dict
548 :let s = string(dict) " String representation of dict
549 :call map(dict, '">> " . v:val') " prepend ">> " to each item
552 1.5 More about variables ~
554 If you need to know the type of a variable or expression, use the |type()|
557 When the '!' flag is included in the 'viminfo' option, global variables that
558 start with an uppercase letter, and don't contain a lowercase letter, are
559 stored in the viminfo file |viminfo-file|.
561 When the 'sessionoptions' option contains "global", global variables that
562 start with an uppercase letter and contain at least one lowercase letter are
563 stored in the session file |session-file|.
565 variable name can be stored where ~
567 My_Var_6 session file
568 MY_VAR_6 viminfo file
571 It's possible to form a variable name with curly braces, see
572 |curly-braces-names|.
574 ==============================================================================
575 2. Expression syntax *expression-syntax*
577 Expression syntax summary, from least to most significant:
579 |expr1| expr2 ? expr1 : expr1 if-then-else
581 |expr2| expr3 || expr3 .. logical OR
583 |expr3| expr4 && expr4 .. logical AND
585 |expr4| expr5 == expr5 equal
586 expr5 != expr5 not equal
587 expr5 > expr5 greater than
588 expr5 >= expr5 greater than or equal
589 expr5 < expr5 smaller than
590 expr5 <= expr5 smaller than or equal
591 expr5 =~ expr5 regexp matches
592 expr5 !~ expr5 regexp doesn't match
594 expr5 ==? expr5 equal, ignoring case
595 expr5 ==# expr5 equal, match case
596 etc. As above, append ? for ignoring case, # for
599 expr5 is expr5 same |List| instance
600 expr5 isnot expr5 different |List| instance
602 |expr5| expr6 + expr6 .. number addition or list concatenation
603 expr6 - expr6 .. number subtraction
604 expr6 . expr6 .. string concatenation
606 |expr6| expr7 * expr7 .. number multiplication
607 expr7 / expr7 .. number division
608 expr7 % expr7 .. number modulo
610 |expr7| ! expr7 logical NOT
615 |expr8| expr8[expr1] byte of a String or item of a |List|
616 expr8[expr1 : expr1] substring of a String or sublist of a |List|
617 expr8.name entry in a |Dictionary|
618 expr8(expr1, ...) function call with |Funcref| variable
620 |expr9| number number constant
621 "string" string constant, backslash is special
622 'string' string constant, ' is doubled
624 {expr1: expr1, ...} |Dictionary|
626 (expr1) nested expression
627 variable internal variable
628 va{ria}ble internal variable with curly braces
629 $VAR environment variable
630 @r contents of register 'r'
631 function(expr1, ...) function call
632 func{ti}on(expr1, ...) function call with curly braces
635 ".." indicates that the operations in this level can be concatenated.
637 &nu || &list && &shell == "csh"
639 All expressions within one level are parsed from left to right.
645 expr2 ? expr1 : expr1
647 The expression before the '?' is evaluated to a number. If it evaluates to
648 non-zero, the result is the value of the expression between the '?' and ':',
649 otherwise the result is the value of the expression after the ':'.
651 :echo lnum == 1 ? "top" : lnum
653 Since the first expression is an "expr2", it cannot contain another ?:. The
654 other two expressions can, thus allow for recursive use of ?:.
656 :echo lnum == 1 ? "top" : lnum == 1000 ? "last" : lnum
658 To keep this readable, using |line-continuation| is suggested: >
665 You should always put a space before the ':', otherwise it can be mistaken for
666 use in a variable such as "a:1".
669 expr2 and expr3 *expr2* *expr3*
672 *expr-barbar* *expr-&&*
673 The "||" and "&&" operators take one argument on each side. The arguments
674 are (converted to) Numbers. The result is:
677 n1 n2 n1 || n2 n1 && n2 ~
679 zero non-zero non-zero zero
680 non-zero zero non-zero zero
681 non-zero non-zero non-zero non-zero
683 The operators can be concatenated, for example: >
685 &nu || &list && &shell == "csh"
687 Note that "&&" takes precedence over "||", so this has the meaning of: >
689 &nu || (&list && &shell == "csh")
691 Once the result is known, the expression "short-circuits", that is, further
692 arguments are not evaluated. This is like what happens in C. For example: >
697 This is valid even if there is no variable called "b" because "a" is non-zero,
698 so the result must be non-zero. Similarly below: >
700 echo exists("b") && b == "yes"
702 This is valid whether "b" has been defined or not. The second clause will
703 only be evaluated if "b" has been defined.
711 Compare two expr5 expressions, resulting in a 0 if it evaluates to false, or 1
712 if it evaluates to true.
714 *expr-==* *expr-!=* *expr->* *expr->=*
715 *expr-<* *expr-<=* *expr-=~* *expr-!~*
716 *expr-==#* *expr-!=#* *expr->#* *expr->=#*
717 *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#*
718 *expr-==?* *expr-!=?* *expr->?* *expr->=?*
719 *expr-<?* *expr-<=?* *expr-=~?* *expr-!~?*
721 use 'ignorecase' match case ignore case ~
725 greater than or equal >= >=# >=?
727 smaller than or equal <= <=# <=?
728 regexp matches =~ =~# =~?
729 regexp doesn't match !~ !~# !~?
731 different instance isnot
734 "abc" ==# "Abc" evaluates to 0
735 "abc" ==? "Abc" evaluates to 1
736 "abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise
739 A |List| can only be compared with a |List| and only "equal", "not equal" and
740 "is" can be used. This compares the values of the list, recursively.
741 Ignoring case means case is ignored when comparing item values.
744 A |Dictionary| can only be compared with a |Dictionary| and only "equal", "not
745 equal" and "is" can be used. This compares the key/values of the |Dictionary|
746 recursively. Ignoring case means case is ignored when comparing item values.
749 A |Funcref| can only be compared with a |Funcref| and only "equal" and "not
750 equal" can be used. Case is never ignored.
752 When using "is" or "isnot" with a |List| this checks if the expressions are
753 referring to the same |List| instance. A copy of a |List| is different from
754 the original |List|. When using "is" without a |List| it is equivalent to
755 using "equal", using "isnot" equivalent to using "not equal". Except that a
756 different type means the values are different. "4 == '4'" is true, "4 is '4'"
759 When comparing a String with a Number, the String is converted to a Number,
760 and the comparison is done on Numbers. This means that "0 == 'x'" is TRUE,
761 because 'x' converted to a Number is zero.
763 When comparing two Strings, this is done with strcmp() or stricmp(). This
764 results in the mathematical difference (comparing byte values), not
765 necessarily the alphabetical difference in the local language.
767 When using the operators with a trailing '#', or the short version and
768 'ignorecase' is off, the comparing is done with strcmp(): case matters.
770 When using the operators with a trailing '?', or the short version and
771 'ignorecase' is set, the comparing is done with stricmp(): case is ignored.
773 'smartcase' is not used.
775 The "=~" and "!~" operators match the lefthand argument with the righthand
776 argument, which is used as a pattern. See |pattern| for what a pattern is.
777 This matching is always done like 'magic' was set and 'cpoptions' is empty, no
778 matter what the actual value of 'magic' or 'cpoptions' is. This makes scripts
779 portable. To avoid backslashes in the regexp pattern to be doubled, use a
780 single-quote string, see |literal-string|.
781 Since a string is considered to be a single line, a multi-line pattern
782 (containing \n, backslash-n) will not match. However, a literal NL character
783 can be matched like an ordinary character. Examples:
784 "foo\nbar" =~ "\n" evaluates to 1
785 "foo\nbar" =~ "\\n" evaluates to 0
788 expr5 and expr6 *expr5* *expr6*
790 expr6 + expr6 .. Number addition or |List| concatenation *expr-+*
791 expr6 - expr6 .. Number subtraction *expr--*
792 expr6 . expr6 .. String concatenation *expr-.*
794 For |Lists| only "+" is possible and then both expr6 must be a list. The
795 result is a new list with the two lists Concatenated.
797 expr7 * expr7 .. number multiplication *expr-star*
798 expr7 / expr7 .. number division *expr-/*
799 expr7 % expr7 .. number modulo *expr-%*
801 For all, except ".", Strings are converted to Numbers.
803 Note the difference between "+" and ".":
805 "123" . "456" = "123456"
807 Since '.' has the same precedence as '+' and '-', you need to read: >
811 That works, since the String "190" is automatically converted to the Number
812 190, which can be added to the Float 90.0. However: >
816 Since '.' has lower precedence than '*'. This does NOT work, since this
817 attempts to concatenate a Float and a String.
819 When dividing a Number by zero the result depends on the value:
820 0 / 0 = -0x80000000 (like NaN for Float)
821 >0 / 0 = 0x7fffffff (like positive infinity)
822 <0 / 0 = -0x7fffffff (like negative infinity)
823 (before Vim 7.2 it was always 0x7fffffff)
825 When the righthand side of '%' is zero, the result is 0.
827 None of these work for |Funcref|s.
829 . and % do not work for Float. *E804*
834 ! expr7 logical NOT *expr-!*
835 - expr7 unary minus *expr-unary--*
836 + expr7 unary plus *expr-unary-+*
838 For '!' non-zero becomes zero, zero becomes one.
839 For '-' the sign of the number is changed.
840 For '+' the number is unchanged.
842 A String will be converted to a Number first.
844 These three can be repeated and mixed. Examples:
852 expr8[expr1] item of String or |List| *expr-[]* *E111*
854 If expr8 is a Number or String this results in a String that contains the
855 expr1'th single byte from expr8. expr8 is used as a String, expr1 as a
856 Number. This doesn't recognize multi-byte encodings, see |byteidx()| for
859 Index zero gives the first character. This is like it works in C. Careful:
860 text column numbers start with one! Example, to get the character under the
862 :let c = getline(".")[col(".") - 1]
864 If the length of the String is less than the index, the result is an empty
865 String. A negative index always results in an empty string (reason: backwards
866 compatibility). Use [-1:] to get the last byte.
868 If expr8 is a |List| then it results the item at index expr1. See |list-index|
869 for possible index values. If the index is out of range this results in an
871 :let item = mylist[-1] " get last item
873 Generally, if a |List| index is equal to or higher than the length of the
874 |List|, or more negative than the length of the |List|, this results in an
878 expr8[expr1a : expr1b] substring or sublist *expr-[:]*
880 If expr8 is a Number or String this results in the substring with the bytes
881 from expr1a to and including expr1b. expr8 is used as a String, expr1a and
882 expr1b are used as a Number. This doesn't recognize multi-byte encodings, see
883 |byteidx()| for computing the indexes.
885 If expr1a is omitted zero is used. If expr1b is omitted the length of the
886 string minus one is used.
888 A negative number can be used to measure from the end of the string. -1 is
889 the last character, -2 the last but one, etc.
891 If an index goes out of range for the string characters are omitted. If
892 expr1b is smaller than expr1a the result is an empty string.
895 :let c = name[-1:] " last byte of a string
896 :let c = name[-2:-2] " last but one byte of a string
897 :let s = line(".")[4:] " from the fifth byte to the end
898 :let s = s[:-3] " remove last two bytes
901 If expr8 is a |List| this results in a new |List| with the items indicated by
902 the indexes expr1a and expr1b. This works like with a String, as explained
903 just above, except that indexes out of range cause an error. Examples: >
904 :let l = mylist[:3] " first four items
905 :let l = mylist[4:4] " List with one item
906 :let l = mylist[:] " shallow copy of a List
908 Using expr8[expr1] or expr8[expr1a : expr1b] on a |Funcref| results in an
912 expr8.name entry in a |Dictionary| *expr-entry*
914 If expr8 is a |Dictionary| and it is followed by a dot, then the following
915 name will be used as a key in the |Dictionary|. This is just like:
918 The name must consist of alphanumeric characters, just like a variable name,
919 but it may start with a number. Curly braces cannot be used.
921 There must not be white space before or after the dot.
924 :let dict = {"one": 1, 2: "two"}
928 Note that the dot is also used for String concatenation. To avoid confusion
929 always put spaces around the dot for String concatenation.
932 expr8(expr1, ...) |Funcref| function call
934 When expr8 is a |Funcref| type variable, invoke the function it refers to.
941 number number constant *expr-number*
943 Decimal, Hexadecimal (starting with 0x or 0X), or Octal (starting with 0).
945 *floating-point-format*
946 Floating point numbers can be written in two forms:
949 [-+]{N}.{M}e[-+]{exp}
951 {N} and {M} are numbers. Both {N} and {M} must be present and can only
953 [-+] means there is an optional plus or minus sign.
954 {exp} is the exponent, power of 10.
955 Only a decimal point is accepted, not a comma. No matter what the current
957 {only when compiled with the |+float| feature}
973 A few useful values to copy&paste: >
974 :let pi = 3.14159265359
975 :let e = 2.71828182846
978 Before floating point was introduced, the text "123.456" was interpreted as
979 the two numbers "123" and "456", both converted to a string and concatenated,
980 resulting in the string "123456". Since this was considered pointless, and we
981 could not find it intentionally being used in Vim scripts, this backwards
982 incompatibility was accepted in favor of being able to use the normal notation
983 for floating point numbers.
985 *floating-point-precision*
986 The precision and range of floating points numbers depends on what "double"
987 means in the library Vim was compiled with. There is no way to change this at
990 The default for displaying a |Float| is to use 6 decimal places, like using
991 printf("%g", f). You can select something else when using the |printf()|
993 :echo printf('%.15e', atan(1))
994 < 7.853981633974483e-01
998 string *expr-string* *E114*
1000 "string" string constant *expr-quote*
1002 Note that double quotes are used.
1004 A string constant accepts these special characters:
1005 \... three-digit octal number (e.g., "\316")
1006 \.. two-digit octal number (must be followed by non-digit)
1007 \. one-digit octal number (must be followed by non-digit)
1008 \x.. byte specified with two hex numbers (e.g., "\x1f")
1009 \x. byte specified with one hex number (must be followed by non-hex char)
1012 \u.... character specified with up to 4 hex numbers, stored according to the
1013 current value of 'encoding' (e.g., "\u02a4")
1014 \U.... same as \u....
1023 \<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W.
1025 Note that "\xff" is stored as the byte 255, which may be invalid in some
1026 encodings. Use "\u00ff" to store character 255 according to the current value
1029 Note that "\000" and "\x00" force the end of the string.
1032 literal-string *literal-string* *E115*
1034 'string' string constant *expr-'*
1036 Note that single quotes are used.
1038 This string is taken as it is. No backslashes are removed or have a special
1039 meaning. The only exception is that two quotes stand for one quote.
1041 Single quoted strings are useful for patterns, so that backslashes do not need
1042 to be doubled. These two commands are equivalent: >
1047 option *expr-option* *E112* *E113*
1049 &option option value, local value if possible
1050 &g:option global option value
1051 &l:option local option value
1054 echo "tabstop is " . &tabstop
1057 Any option name can be used here. See |options|. When using the local value
1058 and there is no buffer-local or window-local value, the global value is used
1062 register *expr-register* *@r*
1064 @r contents of register 'r'
1066 The result is the contents of the named register, as a single string.
1067 Newlines are inserted where required. To get the contents of the unnamed
1068 register use @" or @@. See |registers| for an explanation of the available
1071 When using the '=' register you get the expression itself, not what it
1072 evaluates to. Use |eval()| to evaluate it.
1075 nesting *expr-nesting* *E110*
1077 (expr1) nested expression
1080 environment variable *expr-env*
1081 --------------------
1082 $VAR environment variable
1084 The String value of any environment variable. When it is not defined, the
1085 result is an empty string.
1087 Note that there is a difference between using $VAR directly and using
1088 expand("$VAR"). Using it directly will only expand environment variables that
1089 are known inside the current Vim session. Using expand() will first try using
1090 the environment variables known inside the current Vim session. If that
1091 fails, a shell will be used to expand the variable. This can be slow, but it
1092 does expand all variables that the shell knows about. Example: >
1094 :echo expand("$version")
1095 The first one probably doesn't echo anything, the second echoes the $version
1096 variable (if your shell supports it).
1099 internal variable *expr-variable*
1101 variable internal variable
1102 See below |internal-variables|.
1105 function call *expr-function* *E116* *E118* *E119* *E120*
1107 function(expr1, ...) function call
1108 See below |functions|.
1111 ==============================================================================
1112 3. Internal variable *internal-variables* *E121*
1114 An internal variable name can be made up of letters, digits and '_'. But it
1115 cannot start with a digit. It's also possible to use curly braces, see
1116 |curly-braces-names|.
1118 An internal variable is created with the ":let" command |:let|.
1119 An internal variable is explicitly destroyed with the ":unlet" command
1121 Using a name that is not an internal variable or refers to a variable that has
1122 been destroyed results in an error.
1124 There are several name spaces for variables. Which one is to be used is
1125 specified by what is prepended:
1127 (nothing) In a function: local to a function; otherwise: global
1128 |buffer-variable| b: Local to the current buffer.
1129 |window-variable| w: Local to the current window.
1130 |tabpage-variable| t: Local to the current tab page.
1131 |global-variable| g: Global.
1132 |local-variable| l: Local to a function.
1133 |script-variable| s: Local to a |:source|'ed Vim script.
1134 |function-argument| a: Function argument (only inside a function).
1135 |vim-variable| v: Global, predefined by Vim.
1137 The scope name by itself can be used as a |Dictionary|. For example, to
1138 delete all script-local variables: >
1143 *buffer-variable* *b:var*
1144 A variable name that is preceded with "b:" is local to the current buffer.
1145 Thus you can have several "b:foo" variables, one for each buffer.
1146 This kind of variable is deleted when the buffer is wiped out or deleted with
1149 One local buffer variable is predefined:
1150 *b:changedtick-variable* *changetick*
1151 b:changedtick The total number of changes to the current buffer. It is
1152 incremented for each change. An undo command is also a change
1153 in this case. This can be used to perform an action only when
1154 the buffer has changed. Example: >
1155 :if my_changedtick != b:changedtick
1156 : let my_changedtick = b:changedtick
1160 *window-variable* *w:var*
1161 A variable name that is preceded with "w:" is local to the current window. It
1162 is deleted when the window is closed.
1164 *tabpage-variable* *t:var*
1165 A variable name that is preceded with "t:" is local to the current tab page,
1166 It is deleted when the tab page is closed. {not available when compiled
1167 without the +windows feature}
1169 *global-variable* *g:var*
1170 Inside functions global variables are accessed with "g:". Omitting this will
1171 access a variable local to a function. But "g:" can also be used in any other
1174 *local-variable* *l:var*
1175 Inside functions local variables are accessed without prepending anything.
1176 But you can also prepend "l:" if you like. However, without prepending "l:"
1177 you may run into reserved variable names. For example "count". By itself it
1178 refers to "v:count". Using "l:count" you can have a local variable with the
1181 *script-variable* *s:var*
1182 In a Vim script variables starting with "s:" can be used. They cannot be
1183 accessed from outside of the scripts, thus are local to the script.
1185 They can be used in:
1186 - commands executed while the script is sourced
1187 - functions defined in the script
1188 - autocommands defined in the script
1189 - functions and autocommands defined in functions and autocommands which were
1190 defined in the script (recursively)
1191 - user defined commands defined in the script
1193 - other scripts sourced from this one
1197 Script variables can be used to avoid conflicts with global variable names.
1198 Take this example: >
1201 function MyCounter()
1202 let s:counter = s:counter + 1
1205 command Tick call MyCounter()
1207 You can now invoke "Tick" from any script, and the "s:counter" variable in
1208 that script will not be changed, only the "s:counter" in the script where
1209 "Tick" was defined is used.
1211 Another example that does the same: >
1214 command Tick let s:counter = s:counter + 1 | echo s:counter
1216 When calling a function and invoking a user-defined command, the context for
1217 script variables is set to the script where the function or command was
1220 The script variables are also available when a function is defined inside a
1221 function that is defined in a script. Example: >
1224 function StartCounting(incr)
1226 function MyCounter()
1227 let s:counter = s:counter + 1
1230 function MyCounter()
1231 let s:counter = s:counter - 1
1236 This defines the MyCounter() function either for counting up or counting down
1237 when calling StartCounting(). It doesn't matter from where StartCounting() is
1238 called, the s:counter variable will be accessible in MyCounter().
1240 When the same script is sourced again it will use the same script variables.
1241 They will remain valid as long as Vim is running. This can be used to
1242 maintain a counter: >
1244 if !exists("s:counter")
1246 echo "script executed for the first time"
1248 let s:counter = s:counter + 1
1249 echo "script executed " . s:counter . " times now"
1252 Note that this means that filetype plugins don't get a different set of script
1253 variables for each buffer. Use local buffer variables instead |b:var|.
1256 Predefined Vim variables: *vim-variable* *v:var*
1258 *v:beval_col* *beval_col-variable*
1259 v:beval_col The number of the column, over which the mouse pointer is.
1260 This is the byte index in the |v:beval_lnum| line.
1261 Only valid while evaluating the 'balloonexpr' option.
1263 *v:beval_bufnr* *beval_bufnr-variable*
1264 v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only
1265 valid while evaluating the 'balloonexpr' option.
1267 *v:beval_lnum* *beval_lnum-variable*
1268 v:beval_lnum The number of the line, over which the mouse pointer is. Only
1269 valid while evaluating the 'balloonexpr' option.
1271 *v:beval_text* *beval_text-variable*
1272 v:beval_text The text under or after the mouse pointer. Usually a word as
1273 it is useful for debugging a C program. 'iskeyword' applies,
1274 but a dot and "->" before the position is included. When on a
1275 ']' the text before it is used, including the matching '[' and
1276 word before it. When on a Visual area within one line the
1277 highlighted text is used.
1278 Only valid while evaluating the 'balloonexpr' option.
1280 *v:beval_winnr* *beval_winnr-variable*
1281 v:beval_winnr The number of the window, over which the mouse pointer is. Only
1282 valid while evaluating the 'balloonexpr' option.
1284 *v:char* *char-variable*
1285 v:char Argument for evaluating 'formatexpr'.
1287 *v:charconvert_from* *charconvert_from-variable*
1289 The name of the character encoding of a file to be converted.
1290 Only valid while evaluating the 'charconvert' option.
1292 *v:charconvert_to* *charconvert_to-variable*
1294 The name of the character encoding of a file after conversion.
1295 Only valid while evaluating the 'charconvert' option.
1297 *v:cmdarg* *cmdarg-variable*
1298 v:cmdarg This variable is used for two purposes:
1299 1. The extra arguments given to a file read/write command.
1300 Currently these are "++enc=" and "++ff=". This variable is
1301 set before an autocommand event for a file read/write
1302 command is triggered. There is a leading space to make it
1303 possible to append this variable directly after the
1304 read/write command. Note: The "+cmd" argument isn't
1305 included here, because it will be executed anyway.
1306 2. When printing a PostScript file with ":hardcopy" this is
1307 the argument for the ":hardcopy" command. This can be used
1310 *v:cmdbang* *cmdbang-variable*
1311 v:cmdbang Set like v:cmdarg for a file read/write command. When a "!"
1312 was used the value is 1, otherwise it is 0. Note that this
1313 can only be used in autocommands. For user commands |<bang>|
1316 *v:count* *count-variable*
1317 v:count The count given for the last Normal mode command. Can be used
1318 to get the count before a mapping. Read-only. Example: >
1319 :map _x :<C-U>echo "the count is " . v:count<CR>
1320 < Note: The <C-U> is required to remove the line range that you
1321 get when typing ':' after a count.
1322 When there are two counts, as in "3d2w", they are multiplied,
1323 just like what happens in the command, "d6w" for the example.
1324 Also used for evaluating the 'formatexpr' option.
1325 "count" also works, for backwards compatibility.
1327 *v:count1* *count1-variable*
1328 v:count1 Just like "v:count", but defaults to one when no count is
1331 *v:ctype* *ctype-variable*
1332 v:ctype The current locale setting for characters of the runtime
1333 environment. This allows Vim scripts to be aware of the
1334 current locale encoding. Technical: it's the value of
1335 LC_CTYPE. When not using a locale the value is "C".
1336 This variable can not be set directly, use the |:language|
1340 *v:dying* *dying-variable*
1341 v:dying Normally zero. When a deadly signal is caught it's set to
1342 one. When multiple signals are caught the number increases.
1343 Can be used in an autocommand to check if Vim didn't
1344 terminate normally. {only works on Unix}
1346 :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
1348 *v:errmsg* *errmsg-variable*
1349 v:errmsg Last given error message. It's allowed to set this variable.
1355 < "errmsg" also works, for backwards compatibility.
1357 *v:exception* *exception-variable*
1358 v:exception The value of the exception most recently caught and not
1359 finished. See also |v:throwpoint| and |throw-variables|.
1364 : echo "caught" v:exception
1366 < Output: "caught oops".
1368 *v:fcs_reason* *fcs_reason-variable*
1369 v:fcs_reason The reason why the |FileChangedShell| event was triggered.
1370 Can be used in an autocommand to decide what to do and/or what
1371 to set v:fcs_choice to. Possible values:
1372 deleted file no longer exists
1373 conflict file contents, mode or timestamp was
1374 changed and buffer is modified
1375 changed file contents has changed
1376 mode mode of file changed
1377 time only file timestamp changed
1379 *v:fcs_choice* *fcs_choice-variable*
1380 v:fcs_choice What should happen after a |FileChangedShell| event was
1381 triggered. Can be used in an autocommand to tell Vim what to
1382 do with the affected buffer:
1383 reload Reload the buffer (does not work if
1384 the file was deleted).
1385 ask Ask the user what to do, as if there
1386 was no autocommand. Except that when
1387 only the timestamp changed nothing
1389 <empty> Nothing, the autocommand should do
1390 everything that needs to be done.
1391 The default is empty. If another (invalid) value is used then
1392 Vim behaves like it is empty, there is no warning message.
1394 *v:fname_in* *fname_in-variable*
1395 v:fname_in The name of the input file. Valid while evaluating:
1397 'charconvert' file to be converted
1398 'diffexpr' original file
1399 'patchexpr' original file
1400 'printexpr' file to be printed
1401 And set to the swap file name for |SwapExists|.
1403 *v:fname_out* *fname_out-variable*
1404 v:fname_out The name of the output file. Only valid while
1407 'charconvert' resulting converted file (*)
1408 'diffexpr' output of diff
1409 'patchexpr' resulting patched file
1410 (*) When doing conversion for a write command (e.g., ":w
1411 file") it will be equal to v:fname_in. When doing conversion
1412 for a read command (e.g., ":e file") it will be a temporary
1413 file and different from v:fname_in.
1415 *v:fname_new* *fname_new-variable*
1416 v:fname_new The name of the new version of the file. Only valid while
1417 evaluating 'diffexpr'.
1419 *v:fname_diff* *fname_diff-variable*
1420 v:fname_diff The name of the diff (patch) file. Only valid while
1421 evaluating 'patchexpr'.
1423 *v:folddashes* *folddashes-variable*
1424 v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed
1426 Read-only in the |sandbox|. |fold-foldtext|
1428 *v:foldlevel* *foldlevel-variable*
1429 v:foldlevel Used for 'foldtext': foldlevel of closed fold.
1430 Read-only in the |sandbox|. |fold-foldtext|
1432 *v:foldend* *foldend-variable*
1433 v:foldend Used for 'foldtext': last line of closed fold.
1434 Read-only in the |sandbox|. |fold-foldtext|
1436 *v:foldstart* *foldstart-variable*
1437 v:foldstart Used for 'foldtext': first line of closed fold.
1438 Read-only in the |sandbox|. |fold-foldtext|
1440 *v:insertmode* *insertmode-variable*
1441 v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand
1445 v Virtual Replace mode
1447 *v:key* *key-variable*
1448 v:key Key of the current item of a |Dictionary|. Only valid while
1449 evaluating the expression used with |map()| and |filter()|.
1452 *v:lang* *lang-variable*
1453 v:lang The current locale setting for messages of the runtime
1454 environment. This allows Vim scripts to be aware of the
1455 current language. Technical: it's the value of LC_MESSAGES.
1456 The value is system dependent.
1457 This variable can not be set directly, use the |:language|
1459 It can be different from |v:ctype| when messages are desired
1460 in a different language than what is used for character
1461 encoding. See |multi-lang|.
1463 *v:lc_time* *lc_time-variable*
1464 v:lc_time The current locale setting for time messages of the runtime
1465 environment. This allows Vim scripts to be aware of the
1466 current language. Technical: it's the value of LC_TIME.
1467 This variable can not be set directly, use the |:language|
1468 command. See |multi-lang|.
1470 *v:lnum* *lnum-variable*
1471 v:lnum Line number for the 'foldexpr' |fold-expr| and 'indentexpr'
1472 expressions, tab page number for 'guitablabel' and
1473 'guitabtooltip'. Only valid while one of these expressions is
1474 being evaluated. Read-only when in the |sandbox|.
1476 *v:mouse_win* *mouse_win-variable*
1477 v:mouse_win Window number for a mouse click obtained with |getchar()|.
1478 First window has number 1, like with |winnr()|. The value is
1479 zero when there was no mouse button click.
1481 *v:mouse_lnum* *mouse_lnum-variable*
1482 v:mouse_lnum Line number for a mouse click obtained with |getchar()|.
1483 This is the text line number, not the screen line number. The
1484 value is zero when there was no mouse button click.
1486 *v:mouse_col* *mouse_col-variable*
1487 v:mouse_col Column number for a mouse click obtained with |getchar()|.
1488 This is the screen column number, like with |virtcol()|. The
1489 value is zero when there was no mouse button click.
1491 *v:oldfiles* *oldfiles-variable*
1492 v:oldfiles List of file names that is loaded from the |viminfo| file on
1493 startup. These are the files that Vim remembers marks for.
1494 The length of the List is limited by the ' argument of the
1495 'viminfo' option (default is 100).
1496 Also see |:oldfiles| and |c_#<|.
1497 The List can be modified, but this has no effect on what is
1498 stored in the |viminfo| file later. If you use values other
1499 than String this will cause trouble.
1500 {only when compiled with the +viminfo feature}
1502 *v:operator* *operator-variable*
1503 v:operator The last operator given in Normal mode. This is a single
1504 character except for commands starting with <g> or <z>,
1505 in which case it is two characters. Best used alongside
1506 |v:prevcount| and |v:register|. Useful if you want to cancel
1507 Operator-pending mode and then use the operator, e.g.: >
1508 :omap O <Esc>:call MyMotion(v:operator)<CR>
1509 < The value remains set until another operator is entered, thus
1510 don't expect it to be empty.
1511 v:operator is not set for |:delete|, |:yank| or other Ex
1515 *v:prevcount* *prevcount-variable*
1516 v:prevcount The count given for the last but one Normal mode command.
1517 This is the v:count value of the previous command. Useful if
1518 you want to cancel Visual or Operator-pending mode and then
1519 use the count, e.g.: >
1520 :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
1523 *v:profiling* *profiling-variable*
1524 v:profiling Normally zero. Set to one after using ":profile start".
1527 *v:progname* *progname-variable*
1528 v:progname Contains the name (with path removed) with which Vim was
1529 invoked. Allows you to do special initialisations for "view",
1530 "evim" etc., or any other name you might symlink to Vim.
1533 *v:register* *register-variable*
1534 v:register The name of the register supplied to the last normal mode
1535 command. Empty if none were supplied. |getreg()| |setreg()|
1537 *v:scrollstart* *scrollstart-variable*
1538 v:scrollstart String describing the script or function that caused the
1539 screen to scroll up. It's only set when it is empty, thus the
1540 first reason is remembered. It is set to "Unknown" for a
1542 This can be used to find out why your script causes the
1545 *v:servername* *servername-variable*
1546 v:servername The resulting registered |x11-clientserver| name if any.
1550 v:searchforward *v:searchforward* *searchforward-variable*
1551 Search direction: 1 after a forward search, 0 after a
1552 backward search. It is reset to forward when directly setting
1553 the last search pattern, see |quote/|.
1554 Note that the value is restored when returning from a
1555 function. |function-search-undo|.
1558 *v:shell_error* *shell_error-variable*
1559 v:shell_error Result of the last shell command. When non-zero, the last
1560 shell command had an error. When zero, there was no problem.
1561 This only works when the shell returns the error code to Vim.
1562 The value -1 is often used when the command could not be
1563 executed. Read-only.
1567 : echo 'could not rename "foo" to "bar"!'
1569 < "shell_error" also works, for backwards compatibility.
1571 *v:statusmsg* *statusmsg-variable*
1572 v:statusmsg Last given status message. It's allowed to set this variable.
1574 *v:swapname* *swapname-variable*
1575 v:swapname Only valid when executing |SwapExists| autocommands: Name of
1576 the swap file found. Read-only.
1578 *v:swapchoice* *swapchoice-variable*
1579 v:swapchoice |SwapExists| autocommands can set this to the selected choice
1580 for handling an existing swap file:
1587 The value should be a single-character string. An empty value
1588 results in the user being asked, as would happen when there is
1589 no SwapExists autocommand. The default is empty.
1591 *v:swapcommand* *swapcommand-variable*
1592 v:swapcommand Normal mode command to be executed after a file has been
1593 opened. Can be used for a |SwapExists| autocommand to have
1594 another Vim open the file and jump to the right place. For
1595 example, when jumping to a tag the value is ":tag tagname\r".
1596 For ":edit +cmd file" the value is ":cmd\r".
1598 *v:termresponse* *termresponse-variable*
1599 v:termresponse The escape sequence returned by the terminal for the |t_RV|
1600 termcap entry. It is set when Vim receives an escape sequence
1601 that starts with ESC [ or CSI and ends in a 'c', with only
1602 digits, ';' and '.' in between.
1603 When this option is set, the TermResponse autocommand event is
1604 fired, so that you can react to the response from the
1606 The response from a new xterm is: "<Esc>[ Pp ; Pv ; Pc c". Pp
1607 is the terminal type: 0 for vt100 and 1 for vt220. Pv is the
1608 patch level (since this was introduced in patch 95, it's
1609 always 95 or bigger). Pc is always zero.
1610 {only when compiled with |+termresponse| feature}
1612 *v:this_session* *this_session-variable*
1613 v:this_session Full filename of the last loaded or saved session file. See
1614 |:mksession|. It is allowed to set this variable. When no
1615 session file has been saved, this variable is empty.
1616 "this_session" also works, for backwards compatibility.
1618 *v:throwpoint* *throwpoint-variable*
1619 v:throwpoint The point where the exception most recently caught and not
1620 finished was thrown. Not set when commands are typed. See
1621 also |v:exception| and |throw-variables|.
1626 : echo "Exception from" v:throwpoint
1628 < Output: "Exception from test.vim, line 2"
1630 *v:val* *val-variable*
1631 v:val Value of the current item of a |List| or |Dictionary|. Only
1632 valid while evaluating the expression used with |map()| and
1633 |filter()|. Read-only.
1635 *v:version* *version-variable*
1636 v:version Version number of Vim: Major version number times 100 plus
1637 minor version number. Version 5.0 is 500. Version 5.1 (5.01)
1638 is 501. Read-only. "version" also works, for backwards
1640 Use |has()| to check if a certain patch was included, e.g.: >
1642 < Note that patch numbers are specific to the version, thus both
1643 version 5.0 and 5.1 may have a patch 123, but these are
1644 completely different.
1646 *v:warningmsg* *warningmsg-variable*
1647 v:warningmsg Last given warning message. It's allowed to set this variable.
1649 ==============================================================================
1650 4. Builtin Functions *functions*
1652 See |function-list| for a list grouped by what the function is used for.
1654 (Use CTRL-] on the function name to jump to the full explanation.)
1656 USAGE RESULT DESCRIPTION ~
1658 abs( {expr}) Float or Number absolute value of {expr}
1659 add( {list}, {item}) List append {item} to |List| {list}
1660 append( {lnum}, {string}) Number append {string} below line {lnum}
1661 append( {lnum}, {list}) Number append lines {list} below line {lnum}
1662 argc() Number number of files in the argument list
1663 argidx() Number current index in the argument list
1664 argv( {nr}) String {nr} entry of the argument list
1665 argv( ) List the argument list
1666 atan( {expr}) Float arc tangent of {expr}
1667 browse( {save}, {title}, {initdir}, {default})
1668 String put up a file requester
1669 browsedir( {title}, {initdir}) String put up a directory requester
1670 bufexists( {expr}) Number TRUE if buffer {expr} exists
1671 buflisted( {expr}) Number TRUE if buffer {expr} is listed
1672 bufloaded( {expr}) Number TRUE if buffer {expr} is loaded
1673 bufname( {expr}) String Name of the buffer {expr}
1674 bufnr( {expr}) Number Number of the buffer {expr}
1675 bufwinnr( {expr}) Number window number of buffer {expr}
1676 byte2line( {byte}) Number line number at byte count {byte}
1677 byteidx( {expr}, {nr}) Number byte index of {nr}'th char in {expr}
1678 call( {func}, {arglist} [, {dict}])
1679 any call {func} with arguments {arglist}
1680 ceil( {expr}) Float round {expr} up
1681 changenr() Number current change number
1682 char2nr( {expr}) Number ASCII value of first char in {expr}
1683 cindent( {lnum}) Number C indent for line {lnum}
1684 clearmatches() None clear all matches
1685 col( {expr}) Number column nr of cursor or mark
1686 complete({startcol}, {matches}) String set Insert mode completion
1687 complete_add( {expr}) Number add completion match
1688 complete_check() Number check for key typed during completion
1689 confirm( {msg} [, {choices} [, {default} [, {type}]]])
1690 Number number of choice picked by user
1691 copy( {expr}) any make a shallow copy of {expr}
1692 cos( {expr}) Float cosine of {expr}
1693 count( {list}, {expr} [, {start} [, {ic}]])
1694 Number count how many {expr} are in {list}
1695 cscope_connection( [{num} , {dbpath} [, {prepend}]])
1696 Number checks existence of cscope connection
1697 cursor( {lnum}, {col} [, {coladd}])
1698 Number move cursor to {lnum}, {col}, {coladd}
1699 cursor( {list}) Number move cursor to position in {list}
1700 deepcopy( {expr}) any make a full copy of {expr}
1701 delete( {fname}) Number delete file {fname}
1702 did_filetype() Number TRUE if FileType autocommand event used
1703 diff_filler( {lnum}) Number diff filler lines about {lnum}
1704 diff_hlID( {lnum}, {col}) Number diff highlighting at {lnum}/{col}
1705 empty( {expr}) Number TRUE if {expr} is empty
1706 escape( {string}, {chars}) String escape {chars} in {string} with '\'
1707 eval( {string}) any evaluate {string} into its value
1708 eventhandler( ) Number TRUE if inside an event handler
1709 executable( {expr}) Number 1 if executable {expr} exists
1710 exists( {expr}) Number TRUE if {expr} exists
1711 extend({expr1}, {expr2} [, {expr3}])
1712 List/Dict insert items of {expr2} into {expr1}
1713 expand( {expr} [, {flag}]) String expand special keywords in {expr}
1714 feedkeys( {string} [, {mode}]) Number add key sequence to typeahead buffer
1715 filereadable( {file}) Number TRUE if {file} is a readable file
1716 filewritable( {file}) Number TRUE if {file} is a writable file
1717 filter( {expr}, {string}) List/Dict remove items from {expr} where
1719 finddir( {name}[, {path}[, {count}]])
1720 String find directory {name} in {path}
1721 findfile( {name}[, {path}[, {count}]])
1722 String find file {name} in {path}
1723 float2nr( {expr}) Number convert Float {expr} to a Number
1724 floor( {expr}) Float round {expr} down
1725 fnameescape( {fname}) String escape special characters in {fname}
1726 fnamemodify( {fname}, {mods}) String modify file name
1727 foldclosed( {lnum}) Number first line of fold at {lnum} if closed
1728 foldclosedend( {lnum}) Number last line of fold at {lnum} if closed
1729 foldlevel( {lnum}) Number fold level at {lnum}
1730 foldtext( ) String line displayed for closed fold
1731 foldtextresult( {lnum}) String text for closed fold at {lnum}
1732 foreground( ) Number bring the Vim window to the foreground
1733 function( {name}) Funcref reference to function {name}
1734 garbagecollect( [at_exit]) none free memory, breaking cyclic references
1735 get( {list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
1736 get( {dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
1737 getbufline( {expr}, {lnum} [, {end}])
1738 List lines {lnum} to {end} of buffer {expr}
1739 getbufvar( {expr}, {varname}) any variable {varname} in buffer {expr}
1740 getchar( [expr]) Number get one character from the user
1741 getcharmod( ) Number modifiers for the last typed character
1742 getcmdline() String return the current command-line
1743 getcmdpos() Number return cursor position in command-line
1744 getcmdtype() String return the current command-line type
1745 getcwd() String the current working directory
1746 getfperm( {fname}) String file permissions of file {fname}
1747 getfsize( {fname}) Number size in bytes of file {fname}
1748 getfontname( [{name}]) String name of font being used
1749 getftime( {fname}) Number last modification time of file
1750 getftype( {fname}) String description of type of file {fname}
1751 getline( {lnum}) String line {lnum} of current buffer
1752 getline( {lnum}, {end}) List lines {lnum} to {end} of current buffer
1753 getloclist({nr}) List list of location list items
1754 getmatches() List list of current matches
1755 getpid() Number process ID of Vim
1756 getpos( {expr}) List position of cursor, mark, etc.
1757 getqflist() List list of quickfix items
1758 getreg( [{regname} [, 1]]) String contents of register
1759 getregtype( [{regname}]) String type of register
1760 gettabwinvar( {tabnr}, {winnr}, {name})
1761 any {name} in {winnr} in tab page {tabnr}
1762 getwinposx() Number X coord in pixels of GUI Vim window
1763 getwinposy() Number Y coord in pixels of GUI Vim window
1764 getwinvar( {nr}, {varname}) any variable {varname} in window {nr}
1765 glob( {expr} [, {flag}]) String expand file wildcards in {expr}
1766 globpath( {path}, {expr} [, {flag}])
1767 String do glob({expr}) for all dirs in {path}
1768 has( {feature}) Number TRUE if feature {feature} supported
1769 has_key( {dict}, {key}) Number TRUE if {dict} has entry {key}
1770 haslocaldir() Number TRUE if current window executed |:lcd|
1771 hasmapto( {what} [, {mode} [, {abbr}]])
1772 Number TRUE if mapping to {what} exists
1773 histadd( {history},{item}) String add an item to a history
1774 histdel( {history} [, {item}]) String remove an item from a history
1775 histget( {history} [, {index}]) String get the item {index} from a history
1776 histnr( {history}) Number highest index of a history
1777 hlexists( {name}) Number TRUE if highlight group {name} exists
1778 hlID( {name}) Number syntax ID of highlight group {name}
1779 hostname() String name of the machine Vim is running on
1780 iconv( {expr}, {from}, {to}) String convert encoding of {expr}
1781 indent( {lnum}) Number indent of line {lnum}
1782 index( {list}, {expr} [, {start} [, {ic}]])
1783 Number index in {list} where {expr} appears
1784 input( {prompt} [, {text} [, {completion}]])
1785 String get input from the user
1786 inputdialog( {p} [, {t} [, {c}]]) String like input() but in a GUI dialog
1787 inputlist( {textlist}) Number let the user pick from a choice list
1788 inputrestore() Number restore typeahead
1789 inputsave() Number save and clear typeahead
1790 inputsecret( {prompt} [, {text}]) String like input() but hiding the text
1791 insert( {list}, {item} [, {idx}]) List insert {item} in {list} [before {idx}]
1792 isdirectory( {directory}) Number TRUE if {directory} is a directory
1793 islocked( {expr}) Number TRUE if {expr} is locked
1794 items( {dict}) List key-value pairs in {dict}
1795 join( {list} [, {sep}]) String join {list} items into one String
1796 keys( {dict}) List keys in {dict}
1797 len( {expr}) Number the length of {expr}
1798 libcall( {lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
1799 libcallnr( {lib}, {func}, {arg}) Number idem, but return a Number
1800 line( {expr}) Number line nr of cursor, last line or mark
1801 line2byte( {lnum}) Number byte count of line {lnum}
1802 lispindent( {lnum}) Number Lisp indent for line {lnum}
1803 localtime() Number current time
1804 log10( {expr}) Float logarithm of Float {expr} to base 10
1805 map( {expr}, {string}) List/Dict change each item in {expr} to {expr}
1806 maparg( {name}[, {mode} [, {abbr}]])
1807 String rhs of mapping {name} in mode {mode}
1808 mapcheck( {name}[, {mode} [, {abbr}]])
1809 String check for mappings matching {name}
1810 match( {expr}, {pat}[, {start}[, {count}]])
1811 Number position where {pat} matches in {expr}
1812 matchadd( {group}, {pattern}[, {priority}[, {id}]])
1813 Number highlight {pattern} with {group}
1814 matcharg( {nr}) List arguments of |:match|
1815 matchdelete( {id}) Number delete match identified by {id}
1816 matchend( {expr}, {pat}[, {start}[, {count}]])
1817 Number position where {pat} ends in {expr}
1818 matchlist( {expr}, {pat}[, {start}[, {count}]])
1819 List match and submatches of {pat} in {expr}
1820 matchstr( {expr}, {pat}[, {start}[, {count}]])
1821 String {count}'th match of {pat} in {expr}
1822 max({list}) Number maximum value of items in {list}
1823 min({list}) Number minimum value of items in {list}
1824 mkdir({name} [, {path} [, {prot}]])
1825 Number create directory {name}
1826 mode( [expr]) String current editing mode
1827 nextnonblank( {lnum}) Number line nr of non-blank line >= {lnum}
1828 nr2char( {expr}) String single char with ASCII value {expr}
1829 pathshorten( {expr}) String shorten directory names in a path
1830 pow( {x}, {y}) Float {x} to the power of {y}
1831 prevnonblank( {lnum}) Number line nr of non-blank line <= {lnum}
1832 printf( {fmt}, {expr1}...) String format text
1833 pumvisible() Number whether popup menu is visible
1834 range( {expr} [, {max} [, {stride}]])
1835 List items from {expr} to {max}
1836 readfile({fname} [, {binary} [, {max}]])
1837 List get list of lines from file {fname}
1838 reltime( [{start} [, {end}]]) List get time value
1839 reltimestr( {time}) String turn time value into a String
1840 remote_expr( {server}, {string} [, {idvar}])
1841 String send expression
1842 remote_foreground( {server}) Number bring Vim server to the foreground
1843 remote_peek( {serverid} [, {retvar}])
1844 Number check for reply string
1845 remote_read( {serverid}) String read reply string
1846 remote_send( {server}, {string} [, {idvar}])
1847 String send key sequence
1848 remove( {list}, {idx} [, {end}]) any remove items {idx}-{end} from {list}
1849 remove( {dict}, {key}) any remove entry {key} from {dict}
1850 rename( {from}, {to}) Number rename (move) file from {from} to {to}
1851 repeat( {expr}, {count}) String repeat {expr} {count} times
1852 resolve( {filename}) String get filename a shortcut points to
1853 reverse( {list}) List reverse {list} in-place
1854 round( {expr}) Float round off {expr}
1855 search( {pattern} [, {flags} [, {stopline} [, {timeout}]]])
1856 Number search for {pattern}
1857 searchdecl({name} [, {global} [, {thisblock}]])
1858 Number search for variable declaration
1859 searchpair( {start}, {middle}, {end} [, {flags} [, {skip} [...]]])
1860 Number search for other end of start/end pair
1861 searchpairpos( {start}, {middle}, {end} [, {flags} [, {skip} [...]]])
1862 List search for other end of start/end pair
1863 searchpos( {pattern} [, {flags} [, {stopline} [, {timeout}]]])
1864 List search for {pattern}
1865 server2client( {clientid}, {string})
1866 Number send reply string
1867 serverlist() String get a list of available servers
1868 setbufvar( {expr}, {varname}, {val}) set {varname} in buffer {expr} to {val}
1869 setcmdpos( {pos}) Number set cursor position in command-line
1870 setline( {lnum}, {line}) Number set line {lnum} to {line}
1871 setloclist( {nr}, {list}[, {action}])
1872 Number modify location list using {list}
1873 setmatches( {list}) Number restore a list of matches
1874 setpos( {expr}, {list}) none set the {expr} position to {list}
1875 setqflist( {list}[, {action}]) Number modify quickfix list using {list}
1876 setreg( {n}, {v}[, {opt}]) Number set register to value and type
1877 settabwinvar( {tabnr}, {winnr}, {varname}, {val}) set {varname} in window
1878 {winnr} in tab page {tabnr} to {val}
1879 setwinvar( {nr}, {varname}, {val}) set {varname} in window {nr} to {val}
1880 shellescape( {string} [, {special}])
1881 String escape {string} for use as shell
1883 simplify( {filename}) String simplify filename as much as possible
1884 sin( {expr}) Float sine of {expr}
1885 sort( {list} [, {func}]) List sort {list}, using {func} to compare
1886 soundfold( {word}) String sound-fold {word}
1887 spellbadword() String badly spelled word at cursor
1888 spellsuggest( {word} [, {max} [, {capital}]])
1889 List spelling suggestions
1890 split( {expr} [, {pat} [, {keepempty}]])
1891 List make |List| from {pat} separated {expr}
1892 sqrt( {expr} Float squar root of {expr}
1893 str2float( {expr}) Float convert String to Float
1894 str2nr( {expr} [, {base}]) Number convert String to Number
1895 strftime( {format}[, {time}]) String time in specified format
1896 stridx( {haystack}, {needle}[, {start}])
1897 Number index of {needle} in {haystack}
1898 string( {expr}) String String representation of {expr} value
1899 strlen( {expr}) Number length of the String {expr}
1900 strpart( {src}, {start}[, {len}])
1901 String {len} characters of {src} at {start}
1902 strridx( {haystack}, {needle} [, {start}])
1903 Number last index of {needle} in {haystack}
1904 strtrans( {expr}) String translate string to make it printable
1905 submatch( {nr}) String specific match in ":substitute"
1906 substitute( {expr}, {pat}, {sub}, {flags})
1907 String all {pat} in {expr} replaced with {sub}
1908 synID( {lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
1909 synIDattr( {synID}, {what} [, {mode}])
1910 String attribute {what} of syntax ID {synID}
1911 synIDtrans( {synID}) Number translated syntax ID of {synID}
1912 synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
1913 system( {expr} [, {input}]) String output of shell command/filter {expr}
1914 tabpagebuflist( [{arg}]) List list of buffer numbers in tab page
1915 tabpagenr( [{arg}]) Number number of current or last tab page
1916 tabpagewinnr( {tabarg}[, {arg}])
1917 Number number of current window in tab page
1918 taglist( {expr}) List list of tags matching {expr}
1919 tagfiles() List tags files used
1920 tempname() String name for a temporary file
1921 tolower( {expr}) String the String {expr} switched to lowercase
1922 toupper( {expr}) String the String {expr} switched to uppercase
1923 tr( {src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
1925 trunc( {expr} Float truncate Float {expr}
1926 type( {name}) Number type of variable {name}
1927 values( {dict}) List values in {dict}
1928 virtcol( {expr}) Number screen column of cursor or mark
1929 visualmode( [expr]) String last visual mode used
1930 winbufnr( {nr}) Number buffer number of window {nr}
1931 wincol() Number window column of the cursor
1932 winheight( {nr}) Number height of window {nr}
1933 winline() Number window line of the cursor
1934 winnr( [{expr}]) Number number of current window
1935 winrestcmd() String returns command to restore window sizes
1936 winrestview({dict}) None restore view of current window
1937 winsaveview() Dict save view of current window
1938 winwidth( {nr}) Number width of window {nr}
1939 writefile({list}, {fname} [, {binary}])
1940 Number write list of lines to file {fname}
1943 Return the absolute value of {expr}. When {expr} evaluates to
1944 a |Float| abs() returns a |Float|. When {expr} can be
1945 converted to a |Number| abs() returns a |Number|. Otherwise
1946 abs() gives an error message and returns -1.
1954 {only available when compiled with the |+float| feature}
1956 add({list}, {expr}) *add()*
1957 Append the item {expr} to |List| {list}. Returns the
1958 resulting |List|. Examples: >
1959 :let alist = add([1, 2, 3], item)
1960 :call add(mylist, "woodstock")
1961 < Note that when {expr} is a |List| it is appended as a single
1962 item. Use |extend()| to concatenate |Lists|.
1963 Use |insert()| to add an item at another position.
1966 append({lnum}, {expr}) *append()*
1967 When {expr} is a |List|: Append each item of the |List| as a
1968 text line below line {lnum} in the current buffer.
1969 Otherwise append {expr} as one text line below line {lnum} in
1971 {lnum} can be zero to insert a line before the first one.
1972 Returns 1 for failure ({lnum} out of range or out of memory),
1973 0 for success. Example: >
1974 :let failed = append(line('$'), "# THE END")
1975 :let failed = append(0, ["Chapter 1", "the beginning"])
1978 argc() The result is the number of files in the argument list of the
1979 current window. See |arglist|.
1982 argidx() The result is the current index in the argument list. 0 is
1983 the first file. argc() - 1 is the last one. See |arglist|.
1986 argv([{nr}]) The result is the {nr}th file in the argument list of the
1987 current window. See |arglist|. "argv(0)" is the first one.
1991 : let f = escape(fnameescape(argv(i)), '.')
1992 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>'
1995 < Without the {nr} argument a |List| with the whole |arglist| is
1998 atan({expr}) *atan()*
1999 Return the principal value of the arc tangent of {expr}, in
2000 the range [-pi/2, +pi/2] radians, as a |Float|.
2001 {expr} must evaluate to a |Float| or a |Number|.
2007 {only available when compiled with the |+float| feature}
2010 browse({save}, {title}, {initdir}, {default})
2011 Put up a file requester. This only works when "has("browse")"
2012 returns non-zero (only in some GUI versions).
2013 The input fields are:
2014 {save} when non-zero, select file to write
2015 {title} title for the requester
2016 {initdir} directory to start browsing in
2017 {default} default file name
2018 When the "Cancel" button is hit, something went wrong, or
2019 browsing is not possible, an empty string is returned.
2022 browsedir({title}, {initdir})
2023 Put up a directory requester. This only works when
2024 "has("browse")" returns non-zero (only in some GUI versions).
2025 On systems where a directory browser is not supported a file
2026 browser is used. In that case: select a file in the directory
2028 The input fields are:
2029 {title} title for the requester
2030 {initdir} directory to start browsing in
2031 When the "Cancel" button is hit, something went wrong, or
2032 browsing is not possible, an empty string is returned.
2034 bufexists({expr}) *bufexists()*
2035 The result is a Number, which is non-zero if a buffer called
2037 If the {expr} argument is a number, buffer numbers are used.
2038 If the {expr} argument is a string it must match a buffer name
2039 exactly. The name can be:
2040 - Relative to the current directory.
2042 - The name of a buffer with 'buftype' set to "nofile".
2044 Unlisted buffers will be found.
2045 Note that help files are listed by their short name in the
2046 output of |:buffers|, but bufexists() requires using their
2047 long name to be able to find them.
2048 bufexists() may report a buffer exists, but to use the name
2049 with a |:buffer| command you may need to use |expand()|. Esp
2050 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
2051 Use "bufexists(0)" to test for the existence of an alternate
2054 Obsolete name: buffer_exists().
2056 buflisted({expr}) *buflisted()*
2057 The result is a Number, which is non-zero if a buffer called
2058 {expr} exists and is listed (has the 'buflisted' option set).
2059 The {expr} argument is used like with |bufexists()|.
2061 bufloaded({expr}) *bufloaded()*
2062 The result is a Number, which is non-zero if a buffer called
2063 {expr} exists and is loaded (shown in a window or hidden).
2064 The {expr} argument is used like with |bufexists()|.
2066 bufname({expr}) *bufname()*
2067 The result is the name of a buffer, as it is displayed by the
2069 If {expr} is a Number, that buffer number's name is given.
2070 Number zero is the alternate buffer for the current window.
2071 If {expr} is a String, it is used as a |file-pattern| to match
2072 with the buffer names. This is always done like 'magic' is
2073 set and 'cpoptions' is empty. When there is more than one
2074 match an empty string is returned.
2075 "" or "%" can be used for the current buffer, "#" for the
2077 A full match is preferred, otherwise a match at the start, end
2078 or middle of the buffer name is accepted. If you only want a
2079 full match then put "^" at the start and "$" at the end of the
2081 Listed buffers are found first. If there is a single match
2082 with a listed buffer, that one is returned. Next unlisted
2083 buffers are searched for.
2084 If the {expr} is a String, but you want to use it as a buffer
2085 number, force it to be a Number by adding zero to it: >
2086 :echo bufname("3" + 0)
2087 < If the buffer doesn't exist, or doesn't have a name, an empty
2088 string is returned. >
2089 bufname("#") alternate buffer name
2090 bufname(3) name of buffer 3
2091 bufname("%") name of current buffer
2092 bufname("file2") name of buffer where "file2" matches.
2094 Obsolete name: buffer_name().
2097 bufnr({expr} [, {create}])
2098 The result is the number of a buffer, as it is displayed by
2099 the ":ls" command. For the use of {expr}, see |bufname()|
2101 If the buffer doesn't exist, -1 is returned. Or, if the
2102 {create} argument is present and not zero, a new, unlisted,
2103 buffer is created and its number is returned.
2104 bufnr("$") is the last buffer: >
2105 :let last_buffer = bufnr("$")
2106 < The result is a Number, which is the highest buffer number
2107 of existing buffers. Note that not all buffers with a smaller
2108 number necessarily exist, because ":bwipeout" may have removed
2109 them. Use bufexists() to test for the existence of a buffer.
2111 Obsolete name: buffer_number().
2113 Obsolete name for bufnr("$"): last_buffer_nr().
2115 bufwinnr({expr}) *bufwinnr()*
2116 The result is a Number, which is the number of the first
2117 window associated with buffer {expr}. For the use of {expr},
2118 see |bufname()| above. If buffer {expr} doesn't exist or
2119 there is no such window, -1 is returned. Example: >
2121 echo "A window containing buffer 1 is " . (bufwinnr(1))
2123 < The number can be used with |CTRL-W_w| and ":wincmd w"
2125 Only deals with the current tab page.
2128 byte2line({byte}) *byte2line()*
2129 Return the line number that contains the character at byte
2130 count {byte} in the current buffer. This includes the
2131 end-of-line character, depending on the 'fileformat' option
2132 for the current buffer. The first character has byte count
2134 Also see |line2byte()|, |go| and |:goto|.
2135 {not available when compiled without the |+byte_offset|
2138 byteidx({expr}, {nr}) *byteidx()*
2139 Return byte index of the {nr}'th character in the string
2140 {expr}. Use zero for the first character, it returns zero.
2141 This function is only useful when there are multibyte
2142 characters, otherwise the returned value is equal to {nr}.
2143 Composing characters are counted as a separate character.
2145 echo matchstr(str, ".", byteidx(str, 3))
2146 < will display the fourth character. Another way to do the
2148 let s = strpart(str, byteidx(str, 3))
2149 echo strpart(s, 0, byteidx(s, 1))
2150 < If there are less than {nr} characters -1 is returned.
2151 If there are exactly {nr} characters the length of the string
2154 call({func}, {arglist} [, {dict}]) *call()* *E699*
2155 Call function {func} with the items in |List| {arglist} as
2157 {func} can either be a |Funcref| or the name of a function.
2158 a:firstline and a:lastline are set to the cursor line.
2159 Returns the return value of the called function.
2160 {dict} is for functions with the "dict" attribute. It will be
2161 used to set the local variable "self". |Dictionary-function|
2163 ceil({expr}) *ceil()*
2164 Return the smallest integral value greater than or equal to
2165 {expr} as a |Float| (round up).
2166 {expr} must evaluate to a |Float| or a |Number|.
2174 {only available when compiled with the |+float| feature}
2176 changenr() *changenr()*
2177 Return the number of the most recent change. This is the same
2178 number as what is displayed with |:undolist| and can be used
2179 with the |:undo| command.
2180 When a change was made it is the number of that change. After
2181 redo it is the number of the redone change. After undo it is
2182 one less than the number of the undone change.
2184 char2nr({expr}) *char2nr()*
2185 Return number value of the first char in {expr}. Examples: >
2186 char2nr(" ") returns 32
2187 char2nr("ABC") returns 65
2188 < The current 'encoding' is used. Example for "utf-8": >
2189 char2nr("á") returns 225
2190 char2nr("á"[0]) returns 195
2191 < |nr2char()| does the opposite.
2193 cindent({lnum}) *cindent()*
2194 Get the amount of indent for line {lnum} according the C
2195 indenting rules, as with 'cindent'.
2196 The indent is counted in spaces, the value of 'tabstop' is
2197 relevant. {lnum} is used just like in |getline()|.
2198 When {lnum} is invalid or Vim was not compiled the |+cindent|
2199 feature, -1 is returned.
2202 clearmatches() *clearmatches()*
2203 Clears all matches previously defined by |matchadd()| and the
2207 col({expr}) The result is a Number, which is the byte index of the column
2208 position given with {expr}. The accepted positions are:
2209 . the cursor position
2210 $ the end of the cursor line (the result is the
2211 number of characters in the cursor line plus one)
2212 'x position of mark x (if the mark is not set, 0 is
2214 Additionally {expr} can be [lnum, col]: a |List| with the line
2215 and column number. Most useful when the column is "$", to get
2216 the last column of a specific line. When "lnum" or "col" is
2217 out of range then col() returns zero.
2218 To get the line number use |line()|. To get both use
2220 For the screen column position use |virtcol()|.
2221 Note that only marks in the current file can be used.
2223 col(".") column of cursor
2224 col("$") length of cursor line plus one
2225 col("'t") column of mark t
2226 col("'" . markname) column of mark markname
2227 < The first column is 1. 0 is returned for an error.
2228 For an uppercase mark the column may actually be in another
2230 For the cursor position, when 'virtualedit' is active, the
2231 column is one higher if the cursor is after the end of the
2232 line. This can be used to obtain the column in Insert mode: >
2233 :imap <F2> <C-O>:let save_ve = &ve<CR>
2234 \<C-O>:set ve=all<CR>
2235 \<C-O>:echo col(".") . "\n" <Bar>
2236 \let &ve = save_ve<CR>
2239 complete({startcol}, {matches}) *complete()* *E785*
2240 Set the matches for Insert mode completion.
2241 Can only be used in Insert mode. You need to use a mapping
2242 with CTRL-R = |i_CTRL-R|. It does not work after CTRL-O or
2243 with an expression mapping.
2244 {startcol} is the byte offset in the line where the completed
2245 text start. The text up to the cursor is the original text
2246 that will be replaced by the matches. Use col('.') for an
2247 empty string. "col('.') - 1" will replace one character by a
2249 {matches} must be a |List|. Each |List| item is one match.
2250 See |complete-items| for the kind of items that are possible.
2251 Note that the after calling this function you need to avoid
2252 inserting anything that would completion to stop.
2253 The match can be selected with CTRL-N and CTRL-P as usual with
2254 Insert mode completion. The popup menu will appear if
2255 specified, see |ins-completion-menu|.
2257 inoremap <F5> <C-R>=ListMonths()<CR>
2260 call complete(col('.'), ['January', 'February', 'March',
2261 \ 'April', 'May', 'June', 'July', 'August', 'September',
2262 \ 'October', 'November', 'December'])
2265 < This isn't very useful, but it shows how it works. Note that
2266 an empty string is returned to avoid a zero being inserted.
2268 complete_add({expr}) *complete_add()*
2269 Add {expr} to the list of matches. Only to be used by the
2270 function specified with the 'completefunc' option.
2271 Returns 0 for failure (empty string or out of memory),
2272 1 when the match was added, 2 when the match was already in
2274 See |complete-functions| for an explanation of {expr}. It is
2275 the same as one item in the list that 'omnifunc' would return.
2277 complete_check() *complete_check()*
2278 Check for a key typed while looking for completion matches.
2279 This is to be used when looking for matches takes some time.
2280 Returns non-zero when searching for matches is to be aborted,
2282 Only to be used by the function specified with the
2283 'completefunc' option.
2286 confirm({msg} [, {choices} [, {default} [, {type}]]])
2287 Confirm() offers the user a dialog, from which a choice can be
2288 made. It returns the number of the choice. For the first
2290 Note: confirm() is only supported when compiled with dialog
2291 support, see |+dialog_con| and |+dialog_gui|.
2292 {msg} is displayed in a |dialog| with {choices} as the
2293 alternatives. When {choices} is missing or empty, "&OK" is
2294 used (and translated).
2295 {msg} is a String, use '\n' to include a newline. Only on
2296 some systems the string is wrapped when it doesn't fit.
2297 {choices} is a String, with the individual choices separated
2299 confirm("Save changes?", "&Yes\n&No\n&Cancel")
2300 < The letter after the '&' is the shortcut key for that choice.
2301 Thus you can type 'c' to select "Cancel". The shortcut does
2302 not need to be the first letter: >
2303 confirm("file has been modified", "&Save\nSave &All")
2304 < For the console, the first letter of each choice is used as
2305 the default shortcut key.
2306 The optional {default} argument is the number of the choice
2307 that is made if the user hits <CR>. Use 1 to make the first
2308 choice the default one. Use 0 to not set a default. If
2309 {default} is omitted, 1 is used.
2310 The optional {type} argument gives the type of dialog. This
2311 is only used for the icon of the Win32 GUI. It can be one of
2312 these values: "Error", "Question", "Info", "Warning" or
2313 "Generic". Only the first character is relevant. When {type}
2314 is omitted, "Generic" is used.
2315 If the user aborts the dialog by pressing <Esc>, CTRL-C,
2316 or another valid interrupt key, confirm() returns 0.
2319 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2)
2321 : echo "make up your mind!"
2325 : echo "I prefer bananas myself."
2327 < In a GUI dialog, buttons are used. The layout of the buttons
2328 depends on the 'v' flag in 'guioptions'. If it is included,
2329 the buttons are always put vertically. Otherwise, confirm()
2330 tries to put the buttons in one horizontal line. If they
2331 don't fit, a vertical layout is used anyway. For some systems
2332 the horizontal layout is always used.
2335 copy({expr}) 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 shallow copy is created. This means
2338 that the original |List| can be changed without changing the
2339 copy, and vice versa. But the items are identical, thus
2340 changing an item changes the contents of both |Lists|. Also
2344 Return the cosine of {expr}, measured in radians, as a |Float|.
2345 {expr} must evaluate to a |Float| or a |Number|.
2351 {only available when compiled with the |+float| feature}
2354 count({comp}, {expr} [, {ic} [, {start}]]) *count()*
2355 Return the number of times an item with value {expr} appears
2356 in |List| or |Dictionary| {comp}.
2357 If {start} is given then start with the item with this index.
2358 {start} can only be used with a |List|.
2359 When {ic} is given and it's non-zero then case is ignored.
2362 *cscope_connection()*
2363 cscope_connection([{num} , {dbpath} [, {prepend}]])
2364 Checks for the existence of a |cscope| connection. If no
2365 parameters are specified, then the function returns:
2366 0, if cscope was not available (not compiled in), or
2367 if there are no cscope connections;
2368 1, if there is at least one cscope connection.
2370 If parameters are specified, then the value of {num}
2371 determines how existence of a cscope connection is checked:
2373 {num} Description of existence check
2374 ----- ------------------------------
2375 0 Same as no parameters (e.g., "cscope_connection()").
2376 1 Ignore {prepend}, and use partial string matches for
2378 2 Ignore {prepend}, and use exact string matches for
2380 3 Use {prepend}, use partial string matches for both
2381 {dbpath} and {prepend}.
2382 4 Use {prepend}, use exact string matches for both
2383 {dbpath} and {prepend}.
2385 Note: All string comparisons are case sensitive!
2387 Examples. Suppose we had the following (from ":cs show"): >
2389 # pid database name prepend path
2390 0 27664 cscope.out /usr/local
2392 Invocation Return Val ~
2393 ---------- ---------- >
2394 cscope_connection() 1
2395 cscope_connection(1, "out") 1
2396 cscope_connection(2, "out") 0
2397 cscope_connection(3, "out") 0
2398 cscope_connection(3, "out", "local") 1
2399 cscope_connection(4, "out") 0
2400 cscope_connection(4, "out", "local") 0
2401 cscope_connection(4, "cscope.out", "/usr/local") 1
2403 cursor({lnum}, {col} [, {off}]) *cursor()*
2405 Positions the cursor at the column (byte count) {col} in the
2406 line {lnum}. The first column is one.
2407 When there is one argument {list} this is used as a |List|
2408 with two or three items {lnum}, {col} and {off}. This is like
2409 the return value of |getpos()|, but without the first item.
2410 Does not change the jumplist.
2411 If {lnum} is greater than the number of lines in the buffer,
2412 the cursor will be positioned at the last line in the buffer.
2413 If {lnum} is zero, the cursor will stay in the current line.
2414 If {col} is greater than the number of bytes in the line,
2415 the cursor will be positioned at the last character in the
2417 If {col} is zero, the cursor will stay in the current column.
2418 When 'virtualedit' is used {off} specifies the offset in
2419 screen columns from the start of the character. E.g., a
2420 position within a <Tab> or after the last character.
2423 deepcopy({expr}[, {noref}]) *deepcopy()* *E698*
2424 Make a copy of {expr}. For Numbers and Strings this isn't
2425 different from using {expr} directly.
2426 When {expr} is a |List| a full copy is created. This means
2427 that the original |List| can be changed without changing the
2428 copy, and vice versa. When an item is a |List|, a copy for it
2429 is made, recursively. Thus changing an item in the copy does
2430 not change the contents of the original |List|.
2431 When {noref} is omitted or zero a contained |List| or
2432 |Dictionary| is only copied once. All references point to
2433 this single copy. With {noref} set to 1 every occurrence of a
2434 |List| or |Dictionary| results in a new copy. This also means
2435 that a cyclic reference causes deepcopy() to fail.
2437 Nesting is possible up to 100 levels. When there is an item
2438 that refers back to a higher level making a deep copy with
2439 {noref} set to 1 will fail.
2442 delete({fname}) *delete()*
2443 Deletes the file by the name {fname}. The result is a Number,
2444 which is 0 if the file was deleted successfully, and non-zero
2445 when the deletion failed.
2446 Use |remove()| to delete an item from a |List|.
2449 did_filetype() Returns non-zero when autocommands are being executed and the
2450 FileType event has been triggered at least once. Can be used
2451 to avoid triggering the FileType event again in the scripts
2452 that detect the file type. |FileType|
2453 When editing another file, the counter is reset, thus this
2454 really checks if the FileType event has been triggered for the
2455 current buffer. This allows an autocommand that starts
2456 editing another buffer to set 'filetype' and load a syntax
2459 diff_filler({lnum}) *diff_filler()*
2460 Returns the number of filler lines above line {lnum}.
2461 These are the lines that were inserted at this point in
2462 another diff'ed window. These filler lines are shown in the
2463 display but don't exist in the buffer.
2464 {lnum} is used like with |getline()|. Thus "." is the current
2465 line, "'m" mark m, etc.
2466 Returns 0 if the current window is not in diff mode.
2468 diff_hlID({lnum}, {col}) *diff_hlID()*
2469 Returns the highlight ID for diff mode at line {lnum} column
2470 {col} (byte index). When the current line does not have a
2471 diff change zero is returned.
2472 {lnum} is used like with |getline()|. Thus "." is the current
2473 line, "'m" mark m, etc.
2474 {col} is 1 for the leftmost column, {lnum} is 1 for the first
2476 The highlight ID can be used with |synIDattr()| to obtain
2477 syntax information about the highlighting.
2479 empty({expr}) *empty()*
2480 Return the Number 1 if {expr} is empty, zero otherwise.
2481 A |List| or |Dictionary| is empty when it does not have any
2482 items. A Number is empty when its value is zero.
2483 For a long |List| this is much faster than comparing the
2486 escape({string}, {chars}) *escape()*
2487 Escape the characters in {chars} that occur in {string} with a
2488 backslash. Example: >
2489 :echo escape('c:\program files\vim', ' \')
2491 c:\\program\ files\\vim
2492 < Also see |shellescape()|.
2495 eval({string}) Evaluate {string} and return the result. Especially useful to
2496 turn the result of |string()| back into the original value.
2497 This works for Numbers, Floats, Strings and composites of
2498 them. Also works for |Funcref|s that refer to existing
2501 eventhandler() *eventhandler()*
2502 Returns 1 when inside an event handler. That is that Vim got
2503 interrupted while waiting for the user to type a character,
2504 e.g., when dropping a file on Vim. This means interactive
2505 commands cannot be used. Otherwise zero is returned.
2507 executable({expr}) *executable()*
2508 This function checks if an executable with the name {expr}
2509 exists. {expr} must be the name of the program without any
2511 executable() uses the value of $PATH and/or the normal
2512 searchpath for programs. *PATHEXT*
2513 On MS-DOS and MS-Windows the ".exe", ".bat", etc. can
2514 optionally be included. Then the extensions in $PATHEXT are
2515 tried. Thus if "foo.exe" does not exist, "foo.exe.bat" can be
2516 found. If $PATHEXT is not set then ".exe;.com;.bat;.cmd" is
2517 used. A dot by itself can be used in $PATHEXT to try using
2518 the name without an extension. When 'shell' looks like a
2519 Unix shell, then the name is also tried without adding an
2521 On MS-DOS and MS-Windows it only checks if the file exists and
2522 is not a directory, not if it's really executable.
2523 On MS-Windows an executable in the same directory as Vim is
2524 always found. Since this directory is added to $PATH it
2525 should also work to execute it |win32-PATH|.
2526 The result is a Number:
2529 -1 not implemented on this system
2532 exists({expr}) The result is a Number, which is non-zero if {expr} is
2533 defined, zero otherwise. The {expr} argument is a string,
2534 which contains one of these:
2535 &option-name Vim option (only checks if it exists,
2536 not if it really works)
2537 +option-name Vim option that works.
2538 $ENVNAME environment variable (could also be
2539 done by comparing with an empty
2541 *funcname built-in function (see |functions|)
2542 or user defined function (see
2544 varname internal variable (see
2545 |internal-variables|). Also works
2546 for |curly-braces-names|, |Dictionary|
2547 entries, |List| items, etc. Beware
2548 that evaluating an index may cause an
2549 error message for an invalid
2552 :echo exists("l[5]")
2554 :echo exists("l[xx]")
2555 < E121: Undefined variable: xx
2557 :cmdname Ex command: built-in command, user
2558 command or command modifier |:command|.
2560 1 for match with start of a command
2561 2 full match with a command
2562 3 matches several user commands
2563 To check for a supported command
2564 always check the return value to be 2.
2565 :2match The |:2match| command.
2566 :3match The |:3match| command.
2567 #event autocommand defined for this event
2568 #event#pattern autocommand defined for this event and
2569 pattern (the pattern is taken
2570 literally and compared to the
2571 autocommand patterns character by
2573 #group autocommand group exists
2574 #group#event autocommand defined for this group and
2576 #group#event#pattern
2577 autocommand defined for this group,
2579 ##event autocommand for this event is
2581 For checking for a supported feature use |has()|.
2584 exists("&shortname")
2590 exists("#CursorHold")
2591 exists("#BufReadPre#*.gz")
2592 exists("#filetypeindent")
2593 exists("#filetypeindent#FileType")
2594 exists("#filetypeindent#FileType#*")
2595 exists("##ColorScheme")
2596 < There must be no space between the symbol (&/$/*/#) and the
2598 There must be no extra characters after the name, although in
2599 a few cases this is ignored. That may become more strict in
2600 the future, thus don't count on it!
2603 < NOT working example: >
2604 exists(":make install")
2606 < Note that the argument must be a string, not the name of the
2607 variable itself. For example: >
2609 < This doesn't check for existence of the "bufcount" variable,
2610 but gets the value of "bufcount", and checks if that exists.
2612 expand({expr} [, {flag}]) *expand()*
2613 Expand wildcards and the following special keywords in {expr}.
2614 The result is a String.
2616 When there are several matches, they are separated by <NL>
2617 characters. [Note: in version 5.0 a space was used, which
2618 caused problems when a file name contains a space]
2620 If the expansion fails, the result is an empty string. A name
2621 for a non-existing file is not included.
2623 When {expr} starts with '%', '#' or '<', the expansion is done
2624 like for the |cmdline-special| variables with their associated
2625 modifiers. Here is a short overview:
2628 # alternate file name
2629 #n alternate file name n
2630 <cfile> file name under the cursor
2631 <afile> autocmd file name
2632 <abuf> autocmd buffer number (as a String!)
2633 <amatch> autocmd matched name
2634 <sfile> sourced script file name
2635 <cword> word under the cursor
2636 <cWORD> WORD under the cursor
2637 <client> the {clientid} of the last received
2638 message |server2client()|
2640 :p expand to full path
2641 :h head (last path component removed)
2642 :t tail (last path component only)
2643 :r root (one extension removed)
2647 :let &tags = expand("%:p:h") . "/tags"
2648 < Note that when expanding a string that starts with '%', '#' or
2649 '<', any following text is ignored. This does NOT work: >
2650 :let doesntwork = expand("%:h.bak")
2652 :let doeswork = expand("%:h") . ".bak"
2653 < Also note that expanding "<cfile>" and others only returns the
2654 referenced file name without further expansion. If "<cfile>"
2655 is "~/.cshrc", you need to do another expand() to have the
2656 "~/" expanded into the path of the home directory: >
2657 :echo expand(expand("<cfile>"))
2659 There cannot be white space between the variables and the
2660 following modifier. The |fnamemodify()| function can be used
2661 to modify normal file names.
2663 When using '%' or '#', and the current or alternate file name
2664 is not defined, an empty string is used. Using "%:p" in a
2665 buffer with no name, results in the current directory, with a
2668 When {expr} does not start with '%', '#' or '<', it is
2669 expanded like a file name is expanded on the command line.
2670 'suffixes' and 'wildignore' are used, unless the optional
2671 {flag} argument is given and it is non-zero. Names for
2672 non-existing files are included. The "**" item can be used to
2673 search in a directory tree. For example, to find all "README"
2674 files in the current directory and below: >
2675 :echo expand("**/README")
2677 Expand() can also be used to expand variables and environment
2678 variables that are only known in a shell. But this can be
2679 slow, because a shell must be started. See |expr-env-expand|.
2680 The expanded variable is still handled like a list of file
2681 names. When an environment variable cannot be expanded, it is
2682 left unchanged. Thus ":echo expand('$FOOBAR')" results in
2685 See |glob()| for finding existing files. See |system()| for
2686 getting the raw output of an external command.
2688 extend({expr1}, {expr2} [, {expr3}]) *extend()*
2689 {expr1} and {expr2} must be both |Lists| or both
2692 If they are |Lists|: Append {expr2} to {expr1}.
2693 If {expr3} is given insert the items of {expr2} before item
2694 {expr3} in {expr1}. When {expr3} is zero insert before the
2695 first item. When {expr3} is equal to len({expr1}) then
2696 {expr2} is appended.
2698 :echo sort(extend(mylist, [7, 5]))
2699 :call extend(mylist, [2, 3], 1)
2700 < When {expr1} is the same List as {expr2} then the number of
2701 items copied is equal to the original length of the List.
2702 E.g., when {expr3} is 1 you get N new copies of the first item
2703 (where N is the original length of the List).
2704 Use |add()| to concatenate one item to a list. To concatenate
2705 two lists into a new list use the + operator: >
2706 :let newlist = [1, 2, 3] + [4, 5]
2708 If they are |Dictionaries|:
2709 Add all entries from {expr2} to {expr1}.
2710 If a key exists in both {expr1} and {expr2} then {expr3} is
2711 used to decide what to do:
2712 {expr3} = "keep": keep the value of {expr1}
2713 {expr3} = "force": use the value of {expr2}
2714 {expr3} = "error": give an error message *E737*
2715 When {expr3} is omitted then "force" is assumed.
2717 {expr1} is changed when {expr2} is not empty. If necessary
2718 make a copy of {expr1} first.
2719 {expr2} remains unchanged.
2723 feedkeys({string} [, {mode}]) *feedkeys()*
2724 Characters in {string} are queued for processing as if they
2725 come from a mapping or were typed by the user. They are added
2726 to the end of the typeahead buffer, thus if a mapping is still
2727 being executed these characters come after them.
2728 The function does not wait for processing of keys contained in
2730 To include special keys into {string}, use double-quotes
2731 and "\..." notation |expr-quote|. For example,
2732 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
2733 feedkeys('\<CR>') pushes 5 characters.
2734 If {mode} is absent, keys are remapped.
2735 {mode} is a String, which can contain these character flags:
2736 'm' Remap keys. This is default.
2737 'n' Do not remap keys.
2738 't' Handle keys as if typed; otherwise they are handled as
2739 if coming from a mapping. This matters for undo,
2741 Return value is always 0.
2743 filereadable({file}) *filereadable()*
2744 The result is a Number, which is TRUE when a file with the
2745 name {file} exists, and can be read. If {file} doesn't exist,
2746 or is a directory, the result is FALSE. {file} is any
2747 expression, which is used as a String.
2748 If you don't care about the file being readable you can use
2751 Obsolete name: file_readable().
2754 filewritable({file}) *filewritable()*
2755 The result is a Number, which is 1 when a file with the
2756 name {file} exists, and can be written. If {file} doesn't
2757 exist, or is not writable, the result is 0. If {file} is a
2758 directory, and we can write to it, the result is 2.
2761 filter({expr}, {string}) *filter()*
2762 {expr} must be a |List| or a |Dictionary|.
2763 For each item in {expr} evaluate {string} and when the result
2764 is zero remove the item from the |List| or |Dictionary|.
2765 Inside {string} |v:val| has the value of the current item.
2766 For a |Dictionary| |v:key| has the key of the current item.
2768 :call filter(mylist, 'v:val !~ "OLD"')
2769 < Removes the items where "OLD" appears. >
2770 :call filter(mydict, 'v:key >= 8')
2771 < Removes the items with a key below 8. >
2772 :call filter(var, 0)
2773 < Removes all the items, thus clears the |List| or |Dictionary|.
2775 Note that {string} is the result of expression and is then
2776 used as an expression again. Often it is good to use a
2777 |literal-string| to avoid having to double backslashes.
2779 The operation is done in-place. If you want a |List| or
2780 |Dictionary| to remain unmodified make a copy first: >
2781 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
2783 < Returns {expr}, the |List| or |Dictionary| that was filtered.
2784 When an error is encountered while evaluating {string} no
2785 further items in {expr} are processed.
2788 finddir({name}[, {path}[, {count}]]) *finddir()*
2789 Find directory {name} in {path}. Supports both downwards and
2790 upwards recursive directory searches. See |file-searching|
2791 for the syntax of {path}.
2792 Returns the path of the first found match. When the found
2793 directory is below the current directory a relative path is
2794 returned. Otherwise a full path is returned.
2795 If {path} is omitted or empty then 'path' is used.
2796 If the optional {count} is given, find {count}'s occurrence of
2797 {name} in {path} instead of the first one.
2798 When {count} is negative return all the matches in a |List|.
2799 This is quite similar to the ex-command |:find|.
2800 {only available when compiled with the +file_in_path feature}
2802 findfile({name}[, {path}[, {count}]]) *findfile()*
2803 Just like |finddir()|, but find a file instead of a directory.
2806 :echo findfile("tags.vim", ".;")
2807 < Searches from the directory of the current file upwards until
2808 it finds the file "tags.vim".
2810 float2nr({expr}) *float2nr()*
2811 Convert {expr} to a Number by omitting the part after the
2813 {expr} must evaluate to a |Float| or a Number.
2814 When the value of {expr} is out of range for a |Number| the
2815 result is truncated to 0x7fffffff or -0x7fffffff. NaN results
2820 echo float2nr(-23.45)
2822 echo float2nr(1.0e100)
2824 echo float2nr(-1.0e150)
2826 echo float2nr(1.0e-100)
2828 {only available when compiled with the |+float| feature}
2831 floor({expr}) *floor()*
2832 Return the largest integral value less than or equal to
2833 {expr} as a |Float| (round down).
2834 {expr} must evaluate to a |Float| or a |Number|.
2842 {only available when compiled with the |+float| feature}
2844 fnameescape({string}) *fnameescape()*
2845 Escape {string} for use as file name command argument. All
2846 characters that have a special meaning, such as '%' and '|'
2847 are escaped with a backslash.
2848 For most systems the characters escaped are
2849 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
2850 appears in a filename, it depends on the value of 'isfname'.
2851 A leading '+' and '>' is also escaped (special after |:edit|
2852 and |:write|). And a "-" by itself (special after |:cd|).
2854 :let fname = '+some str%nge|name'
2855 :exe "edit " . fnameescape(fname)
2856 < results in executing: >
2857 edit \+some\ str\%nge\|name
2859 fnamemodify({fname}, {mods}) *fnamemodify()*
2860 Modify file name {fname} according to {mods}. {mods} is a
2861 string of characters like it is used for file names on the
2862 command line. See |filename-modifiers|.
2864 :echo fnamemodify("main.c", ":p:h")
2866 /home/mool/vim/vim/src
2867 < Note: Environment variables don't work in {fname}, use
2868 |expand()| first then.
2870 foldclosed({lnum}) *foldclosed()*
2871 The result is a Number. If the line {lnum} is in a closed
2872 fold, the result is the number of the first line in that fold.
2873 If the line {lnum} is not in a closed fold, -1 is returned.
2875 foldclosedend({lnum}) *foldclosedend()*
2876 The result is a Number. If the line {lnum} is in a closed
2877 fold, the result is the number of the last line in that fold.
2878 If the line {lnum} is not in a closed fold, -1 is returned.
2880 foldlevel({lnum}) *foldlevel()*
2881 The result is a Number, which is the foldlevel of line {lnum}
2882 in the current buffer. For nested folds the deepest level is
2883 returned. If there is no fold at line {lnum}, zero is
2884 returned. It doesn't matter if the folds are open or closed.
2885 When used while updating folds (from 'foldexpr') -1 is
2886 returned for lines where folds are still to be updated and the
2887 foldlevel is unknown. As a special case the level of the
2888 previous line is usually available.
2891 foldtext() Returns a String, to be displayed for a closed fold. This is
2892 the default function used for the 'foldtext' option and should
2893 only be called from evaluating 'foldtext'. It uses the
2894 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
2895 The returned string looks like this: >
2896 +-- 45 lines: abcdef
2897 < The number of dashes depends on the foldlevel. The "45" is
2898 the number of lines in the fold. "abcdef" is the text in the
2899 first non-blank line of the fold. Leading white space, "//"
2900 or "/*" and the text from the 'foldmarker' and 'commentstring'
2902 {not available when compiled without the |+folding| feature}
2904 foldtextresult({lnum}) *foldtextresult()*
2905 Returns the text that is displayed for the closed fold at line
2906 {lnum}. Evaluates 'foldtext' in the appropriate context.
2907 When there is no closed fold at {lnum} an empty string is
2909 {lnum} is used like with |getline()|. Thus "." is the current
2910 line, "'m" mark m, etc.
2911 Useful when exporting folded text, e.g., to HTML.
2912 {not available when compiled without the |+folding| feature}
2915 foreground() Move the Vim window to the foreground. Useful when sent from
2916 a client to a Vim server. |remote_send()|
2917 On Win32 systems this might not work, the OS does not always
2918 allow a window to bring itself to the foreground. Use
2919 |remote_foreground()| instead.
2920 {only in the Win32, Athena, Motif and GTK GUI versions and the
2921 Win32 console version}
2924 function({name}) *function()* *E700*
2925 Return a |Funcref| variable that refers to function {name}.
2926 {name} can be a user defined function or an internal function.
2929 garbagecollect([at_exit]) *garbagecollect()*
2930 Cleanup unused |Lists| and |Dictionaries| that have circular
2931 references. There is hardly ever a need to invoke this
2932 function, as it is automatically done when Vim runs out of
2933 memory or is waiting for the user to press a key after
2934 'updatetime'. Items without circular references are always
2935 freed when they become unused.
2936 This is useful if you have deleted a very big |List| and/or
2937 |Dictionary| with circular references in a script that runs
2939 When the optional "at_exit" argument is one, garbage
2940 collection will also be done when exiting Vim, if it wasn't
2941 done before. This is useful when checking for memory leaks.
2943 get({list}, {idx} [, {default}]) *get()*
2944 Get item {idx} from |List| {list}. When this item is not
2945 available return {default}. Return zero when {default} is
2947 get({dict}, {key} [, {default}])
2948 Get item with key {key} from |Dictionary| {dict}. When this
2949 item is not available return {default}. Return zero when
2950 {default} is omitted.
2953 getbufline({expr}, {lnum} [, {end}])
2954 Return a |List| with the lines starting from {lnum} to {end}
2955 (inclusive) in the buffer {expr}. If {end} is omitted, a
2956 |List| with only the line {lnum} is returned.
2958 For the use of {expr}, see |bufname()| above.
2960 For {lnum} and {end} "$" can be used for the last line of the
2961 buffer. Otherwise a number must be used.
2963 When {lnum} is smaller than 1 or bigger than the number of
2964 lines in the buffer, an empty |List| is returned.
2966 When {end} is greater than the number of lines in the buffer,
2967 it is treated as {end} is set to the number of lines in the
2968 buffer. When {end} is before {lnum} an empty |List| is
2971 This function works only for loaded buffers. For unloaded and
2972 non-existing buffers, an empty |List| is returned.
2975 :let lines = getbufline(bufnr("myfile"), 1, "$")
2977 getbufvar({expr}, {varname}) *getbufvar()*
2978 The result is the value of option or local buffer variable
2979 {varname} in buffer {expr}. Note that the name without "b:"
2981 When {varname} is empty returns a dictionary with all the
2982 buffer-local variables.
2983 This also works for a global or buffer-local option, but it
2984 doesn't work for a global variable, window-local variable or
2985 window-local option.
2986 For the use of {expr}, see |bufname()| above.
2987 When the buffer or variable doesn't exist an empty string is
2988 returned, there is no error message.
2990 :let bufmodified = getbufvar(1, "&mod")
2991 :echo "todo myvar = " . getbufvar("todo", "myvar")
2993 getchar([expr]) *getchar()*
2994 Get a single character from the user or input stream.
2995 If [expr] is omitted, wait until a character is available.
2996 If [expr] is 0, only get a character when one is available.
2997 Return zero otherwise.
2998 If [expr] is 1, only check if a character is available, it is
2999 not consumed. Return zero if no character available.
3001 Without {expr} and when {expr} is 0 a whole character or
3002 special key is returned. If it is an 8-bit character, the
3003 result is a number. Use nr2char() to convert it to a String.
3004 Otherwise a String is returned with the encoded character.
3005 For a special key it's a sequence of bytes starting with 0x80
3006 (decimal: 128). This is the same value as the string
3007 "\<Key>", e.g., "\<Left>". The returned value is also a
3008 String when a modifier (shift, control, alt) was used that is
3009 not included in the character.
3011 When {expr} is 1 only the first byte is returned. For a
3012 one-byte character it is the character itself as a number.
3013 Use nr2char() to convert it to a String.
3015 When the user clicks a mouse button, the mouse event will be
3016 returned. The position can then be found in |v:mouse_col|,
3017 |v:mouse_lnum| and |v:mouse_win|. This example positions the
3018 mouse as it would normally happen: >
3020 if c == "\<LeftMouse>" && v:mouse_win > 0
3021 exe v:mouse_win . "wincmd w"
3023 exe "normal " . v:mouse_col . "|"
3026 There is no prompt, you will somehow have to make clear to the
3027 user that a character has to be typed.
3028 There is no mapping for the character.
3029 Key codes are replaced, thus when the user presses the <Del>
3030 key you get the code for the <Del> key, not the raw character
3031 sequence. Examples: >
3032 getchar() == "\<Del>"
3033 getchar() == "\<S-Left>"
3034 < This example redefines "f" to ignore case: >
3035 :nmap f :call FindChar()<CR>
3036 :function FindChar()
3037 : let c = nr2char(getchar())
3038 : while col('.') < col('$') - 1
3040 : if getline('.')[col('.') - 1] ==? c
3046 getcharmod() *getcharmod()*
3047 The result is a Number which is the state of the modifiers for
3048 the last obtained character with getchar() or in another way.
3049 These values are added together:
3053 16 mouse double click
3054 32 mouse triple click
3055 64 mouse quadruple click
3056 128 Macintosh only: command
3057 Only the modifiers that have not been included in the
3058 character itself are obtained. Thus Shift-a results in "A"
3061 getcmdline() *getcmdline()*
3062 Return the current command-line. Only works when the command
3063 line is being edited, thus requires use of |c_CTRL-\_e| or
3066 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
3067 < Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
3069 getcmdpos() *getcmdpos()*
3070 Return the position of the cursor in the command line as a
3071 byte count. The first column is 1.
3072 Only works when editing the command line, thus requires use of
3073 |c_CTRL-\_e| or |c_CTRL-R_=|. Returns 0 otherwise.
3074 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
3076 getcmdtype() *getcmdtype()*
3077 Return the current command-line type. Possible return values
3080 > debug mode command |debug-mode|
3081 / forward search command
3082 ? backward search command
3084 - |:insert| or |:append| command
3085 Only works when editing the command line, thus requires use of
3086 |c_CTRL-\_e| or |c_CTRL-R_=|. Returns an empty string
3088 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
3091 getcwd() The result is a String, which is the name of the current
3094 getfsize({fname}) *getfsize()*
3095 The result is a Number, which is the size in bytes of the
3097 If {fname} is a directory, 0 is returned.
3098 If the file {fname} can't be found, -1 is returned.
3099 If the size of {fname} is too big to fit in a Number then -2
3102 getfontname([{name}]) *getfontname()*
3103 Without an argument returns the name of the normal font being
3104 used. Like what is used for the Normal highlight group
3106 With an argument a check is done whether {name} is a valid
3107 font name. If not then an empty string is returned.
3108 Otherwise the actual font name is returned, or {name} if the
3109 GUI does not support obtaining the real name.
3110 Only works when the GUI is running, thus not in your vimrc or
3111 gvimrc file. Use the |GUIEnter| autocommand to use this
3112 function just after the GUI has started.
3113 Note that the GTK 2 GUI accepts any font name, thus checking
3114 for a valid name does not work.
3116 getfperm({fname}) *getfperm()*
3117 The result is a String, which is the read, write, and execute
3118 permissions of the given file {fname}.
3119 If {fname} does not exist or its directory cannot be read, an
3120 empty string is returned.
3121 The result is of the form "rwxrwxrwx", where each group of
3122 "rwx" flags represent, in turn, the permissions of the owner
3123 of the file, the group the file belongs to, and other users.
3124 If a user does not have a given permission the flag for this
3125 is replaced with the string "-". Example: >
3126 :echo getfperm("/etc/passwd")
3127 < This will hopefully (from a security point of view) display
3128 the string "rw-r--r--" or even "rw-------".
3130 getftime({fname}) *getftime()*
3131 The result is a Number, which is the last modification time of
3132 the given file {fname}. The value is measured as seconds
3133 since 1st Jan 1970, and may be passed to strftime(). See also
3134 |localtime()| and |strftime()|.
3135 If the file {fname} can't be found -1 is returned.
3137 getftype({fname}) *getftype()*
3138 The result is a String, which is a description of the kind of
3139 file of the given file {fname}.
3140 If {fname} does not exist an empty string is returned.
3141 Here is a table over different kinds of files and their
3145 Symbolic link "link"
3147 Character device "cdev"
3153 < Note that a type such as "link" will only be returned on
3154 systems that support it. On some systems only "dir" and
3155 "file" are returned.
3158 getline({lnum} [, {end}])
3159 Without {end} the result is a String, which is line {lnum}
3160 from the current buffer. Example: >
3162 < When {lnum} is a String that doesn't start with a
3163 digit, line() is called to translate the String into a Number.
3164 To get the line under the cursor: >
3166 < When {lnum} is smaller than 1 or bigger than the number of
3167 lines in the buffer, an empty string is returned.
3169 When {end} is given the result is a |List| where each item is
3170 a line from the current buffer in the range {lnum} to {end},
3171 including line {end}.
3172 {end} is used in the same way as {lnum}.
3173 Non-existing lines are silently omitted.
3174 When {end} is before {lnum} an empty |List| is returned.
3176 :let start = line('.')
3177 :let end = search("^$") - 1
3178 :let lines = getline(start, end)
3180 < To get lines from another buffer see |getbufline()|
3182 getloclist({nr}) *getloclist()*
3183 Returns a list with all the entries in the location list for
3184 window {nr}. When {nr} is zero the current window is used.
3185 For a location list window, the displayed location list is
3186 returned. For an invalid window number {nr}, an empty list is
3187 returned. Otherwise, same as |getqflist()|.
3189 getmatches() *getmatches()*
3190 Returns a |List| with all matches previously defined by
3191 |matchadd()| and the |:match| commands. |getmatches()| is
3192 useful in combination with |setmatches()|, as |setmatches()|
3193 can restore a list of matches saved by |getmatches()|.
3196 < [{'group': 'MyGroup1', 'pattern': 'TODO',
3197 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3198 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3199 :let m = getmatches()
3200 :call clearmatches()
3205 < [{'group': 'MyGroup1', 'pattern': 'TODO',
3206 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3207 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3211 getqflist() *getqflist()*
3212 Returns a list with all the current quickfix errors. Each
3213 list item is a dictionary with these entries:
3214 bufnr number of buffer that has the file name, use
3215 bufname() to get the name
3216 lnum line number in the buffer (first line is 1)
3217 col column number (first column is 1)
3218 vcol non-zero: "col" is visual column
3219 zero: "col" is byte index
3221 pattern search pattern used to locate the error
3222 text description of the error
3223 type type of the error, 'E', '1', etc.
3224 valid non-zero: recognized error message
3226 When there is no error list or it's empty an empty list is
3227 returned. Quickfix list entries with non-existing buffer
3228 number are returned with "bufnr" set to zero.
3230 Useful application: Find pattern matches in multiple files and
3231 do something with them: >
3232 :vimgrep /theword/jg *.c
3233 :for d in getqflist()
3234 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
3238 getreg([{regname} [, 1]]) *getreg()*
3239 The result is a String, which is the contents of register
3240 {regname}. Example: >
3241 :let cliptext = getreg('*')
3242 < getreg('=') returns the last evaluated value of the expression
3243 register. (For use in maps.)
3244 getreg('=', 1) returns the expression itself, so that it can
3245 be restored with |setreg()|. For other registers the extra
3246 argument is ignored, thus you can always give it.
3247 If {regname} is not specified, |v:register| is used.
3250 getregtype([{regname}]) *getregtype()*
3251 The result is a String, which is type of register {regname}.
3252 The value will be one of:
3253 "v" for |characterwise| text
3254 "V" for |linewise| text
3255 "<CTRL-V>{width}" for |blockwise-visual| text
3256 0 for an empty or unknown register
3257 <CTRL-V> is one character with value 0x16.
3258 If {regname} is not specified, |v:register| is used.
3260 gettabwinvar({tabnr}, {winnr}, {varname}) *gettabwinvar()*
3261 Get the value of window-local variable {varname} in window
3262 {winnr} in tab page {tabnr}.
3263 When {varname} starts with "&" get the value of a window-local
3265 Tabs are numbered starting with one. For the current tabpage
3267 When {winnr} is zero the current window is used.
3268 This also works for a global option, buffer-local option and
3269 window-local option, but it doesn't work for a global variable
3270 or buffer-local variable.
3271 When {varname} is empty a dictionary with all window-local
3272 variables is returned.
3273 Note that {varname} must be the name without "w:".
3275 :let list_is_on = gettabwinvar(1, 2, '&list')
3276 :echo "myvar = " . gettabwinvar(3, 1, 'myvar')
3279 getwinposx() The result is a Number, which is the X coordinate in pixels of
3280 the left hand side of the GUI Vim window. The result will be
3281 -1 if the information is not available.
3284 getwinposy() The result is a Number, which is the Y coordinate in pixels of
3285 the top of the GUI Vim window. The result will be -1 if the
3286 information is not available.
3288 getwinvar({winnr}, {varname}) *getwinvar()*
3289 Like |gettabwinvar()| for the current tabpage.
3291 :let list_is_on = getwinvar(2, '&list')
3292 :echo "myvar = " . getwinvar(1, 'myvar')
3294 glob({expr} [, {flag}]) *glob()*
3295 Expand the file wildcards in {expr}. See |wildcards| for the
3296 use of special characters.
3297 The result is a String.
3298 When there are several matches, they are separated by <NL>
3300 Unless the optional {flag} argument is given and is non-zero,
3301 the 'suffixes' and 'wildignore' options apply: Names matching
3302 one of the patterns in 'wildignore' will be skipped and
3303 'suffixes' affect the ordering of matches.
3304 If the expansion fails, the result is an empty string.
3305 A name for a non-existing file is not included.
3307 For most systems backticks can be used to get files names from
3308 any external command. Example: >
3309 :let tagfiles = glob("`find . -name tags -print`")
3310 :let &tags = substitute(tagfiles, "\n", ",", "g")
3311 < The result of the program inside the backticks should be one
3312 item per line. Spaces inside an item are allowed.
3314 See |expand()| for expanding special Vim variables. See
3315 |system()| for getting the raw output of an external command.
3317 globpath({path}, {expr} [, {flag}]) *globpath()*
3318 Perform glob() on all directories in {path} and concatenate
3319 the results. Example: >
3320 :echo globpath(&rtp, "syntax/c.vim")
3321 < {path} is a comma-separated list of directory names. Each
3322 directory name is prepended to {expr} and expanded like with
3323 |glob()|. A path separator is inserted when needed.
3324 To add a comma inside a directory name escape it with a
3325 backslash. Note that on MS-Windows a directory may have a
3326 trailing backslash, remove it if you put a comma after it.
3327 If the expansion fails for one of the directories, there is no
3329 Unless the optional {flag} argument is given and is non-zero,
3330 the 'suffixes' and 'wildignore' options apply: Names matching
3331 one of the patterns in 'wildignore' will be skipped and
3332 'suffixes' affect the ordering of matches.
3334 The "**" item can be used to search in a directory tree.
3335 For example, to find all "README.txt" files in the directories
3336 in 'runtimepath' and below: >
3337 :echo globpath(&rtp, "**/README.txt")
3338 < Upwards search and limiting the depth of "**" is not
3339 supported, thus using 'path' will not always work properly.
3342 has({feature}) The result is a Number, which is 1 if the feature {feature} is
3343 supported, zero otherwise. The {feature} argument is a
3344 string. See |feature-list| below.
3345 Also see |exists()|.
3348 has_key({dict}, {key}) *has_key()*
3349 The result is a Number, which is 1 if |Dictionary| {dict} has
3350 an entry with key {key}. Zero otherwise.
3352 haslocaldir() *haslocaldir()*
3353 The result is a Number, which is 1 when the current
3354 window has set a local path via |:lcd|, and 0 otherwise.
3356 hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
3357 The result is a Number, which is 1 if there is a mapping that
3358 contains {what} in somewhere in the rhs (what it is mapped to)
3359 and this mapping exists in one of the modes indicated by
3361 When {abbr} is there and it is non-zero use abbreviations
3362 instead of mappings. Don't forget to specify Insert and/or
3364 Both the global mappings and the mappings local to the current
3365 buffer are checked for a match.
3366 If no matching mapping is found 0 is returned.
3367 The following characters are recognized in {mode}:
3370 o Operator-pending mode
3372 l Language-Argument ("r", "f", "t", etc.)
3374 When {mode} is omitted, "nvo" is used.
3376 This function is useful to check if a mapping already exists
3377 to a function in a Vim script. Example: >
3378 :if !hasmapto('\ABCdoit')
3379 : map <Leader>d \ABCdoit
3381 < This installs the mapping to "\ABCdoit" only if there isn't
3382 already a mapping to "\ABCdoit".
3384 histadd({history}, {item}) *histadd()*
3385 Add the String {item} to the history {history} which can be
3386 one of: *hist-names*
3387 "cmd" or ":" command line history
3388 "search" or "/" search pattern history
3389 "expr" or "=" typed expression history
3390 "input" or "@" input line history
3391 If {item} does already exist in the history, it will be
3392 shifted to become the newest entry.
3393 The result is a Number: 1 if the operation was successful,
3394 otherwise 0 is returned.
3397 :call histadd("input", strftime("%Y %b %d"))
3398 :let date=input("Enter date: ")
3399 < This function is not available in the |sandbox|.
3401 histdel({history} [, {item}]) *histdel()*
3402 Clear {history}, i.e. delete all its entries. See |hist-names|
3403 for the possible values of {history}.
3405 If the parameter {item} evaluates to a String, it is used as a
3406 regular expression. All entries matching that expression will
3407 be removed from the history (if there are any).
3408 Upper/lowercase must match, unless "\c" is used |/\c|.
3409 If {item} evaluates to a Number, it will be interpreted as
3410 an index, see |:history-indexing|. The respective entry will
3411 be removed if it exists.
3413 The result is a Number: 1 for a successful operation,
3414 otherwise 0 is returned.
3417 Clear expression register history: >
3418 :call histdel("expr")
3420 Remove all entries starting with "*" from the search history: >
3421 :call histdel("/", '^\*')
3423 The following three are equivalent: >
3424 :call histdel("search", histnr("search"))
3425 :call histdel("search", -1)
3426 :call histdel("search", '^'.histget("search", -1).'$')
3428 To delete the last search pattern and use the last-but-one for
3429 the "n" command and 'hlsearch': >
3430 :call histdel("search", -1)
3431 :let @/ = histget("search", -1)
3433 histget({history} [, {index}]) *histget()*
3434 The result is a String, the entry with Number {index} from
3435 {history}. See |hist-names| for the possible values of
3436 {history}, and |:history-indexing| for {index}. If there is
3437 no such entry, an empty String is returned. When {index} is
3438 omitted, the most recent item from the history is used.
3441 Redo the second last search from history. >
3442 :execute '/' . histget("search", -2)
3444 < Define an Ex command ":H {num}" that supports re-execution of
3445 the {num}th entry from the output of |:history|. >
3446 :command -nargs=1 H execute histget("cmd", 0+<args>)
3448 histnr({history}) *histnr()*
3449 The result is the Number of the current entry in {history}.
3450 See |hist-names| for the possible values of {history}.
3451 If an error occurred, -1 is returned.
3454 :let inp_index = histnr("expr")
3456 hlexists({name}) *hlexists()*
3457 The result is a Number, which is non-zero if a highlight group
3458 called {name} exists. This is when the group has been
3459 defined in some way. Not necessarily when highlighting has
3460 been defined for it, it may also have been used for a syntax
3462 *highlight_exists()*
3463 Obsolete name: highlight_exists().
3466 hlID({name}) The result is a Number, which is the ID of the highlight group
3467 with name {name}. When the highlight group doesn't exist,
3469 This can be used to retrieve information about the highlight
3470 group. For example, to get the background color of the
3472 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
3474 Obsolete name: highlightID().
3476 hostname() *hostname()*
3477 The result is a String, which is the name of the machine on
3478 which Vim is currently running. Machine names greater than
3479 256 characters long are truncated.
3481 iconv({expr}, {from}, {to}) *iconv()*
3482 The result is a String, which is the text {expr} converted
3483 from encoding {from} to encoding {to}.
3484 When the conversion fails an empty string is returned.
3485 The encoding names are whatever the iconv() library function
3486 can accept, see ":!man 3 iconv".
3487 Most conversions require Vim to be compiled with the |+iconv|
3488 feature. Otherwise only UTF-8 to latin1 conversion and back
3490 This can be used to display messages with special characters,
3491 no matter what 'encoding' is set to. Write the message in
3493 echo iconv(utf8_str, "utf-8", &enc)
3494 < Note that Vim uses UTF-8 for all Unicode encodings, conversion
3495 from/to UCS-2 is automatically changed to use UTF-8. You
3496 cannot use UCS-2 in a string anyway, because of the NUL bytes.
3497 {only available when compiled with the +multi_byte feature}
3500 indent({lnum}) The result is a Number, which is indent of line {lnum} in the
3501 current buffer. The indent is counted in spaces, the value
3502 of 'tabstop' is relevant. {lnum} is used just like in
3504 When {lnum} is invalid -1 is returned.
3507 index({list}, {expr} [, {start} [, {ic}]]) *index()*
3508 Return the lowest index in |List| {list} where the item has a
3509 value equal to {expr}. There is no automatic conversion, so
3510 the String "4" is different from the Number 4. And the number
3511 4 is different from the Float 4.0. The value of 'ignorecase'
3512 is not used here, case always matters.
3513 If {start} is given then start looking at the item with index
3514 {start} (may be negative for an item relative to the end).
3515 When {ic} is given and it is non-zero, ignore case. Otherwise
3517 -1 is returned when {expr} is not found in {list}.
3519 :let idx = index(words, "the")
3520 :if index(numbers, 123) >= 0
3523 input({prompt} [, {text} [, {completion}]]) *input()*
3524 The result is a String, which is whatever the user typed on
3525 the command-line. The parameter is either a prompt string, or
3526 a blank string (for no prompt). A '\n' can be used in the
3527 prompt to start a new line.
3528 The highlighting set with |:echohl| is used for the prompt.
3529 The input is entered just like a command-line, with the same
3530 editing commands and mappings. There is a separate history
3531 for lines typed for input().
3533 :if input("Coffee or beer? ") == "beer"
3537 If the optional {text} is present and not empty, this is used
3538 for the default reply, as if the user typed this. Example: >
3539 :let color = input("Color? ", "white")
3541 < The optional {completion} argument specifies the type of
3542 completion supported for the input. Without it completion is
3543 not performed. The supported completion types are the same as
3544 that can be supplied to a user-defined command using the
3545 "-complete=" argument. Refer to |:command-completion| for
3546 more information. Example: >
3547 let fname = input("File: ", "", "file")
3549 NOTE: This function must not be used in a startup file, for
3550 the versions that only run in GUI mode (e.g., the Win32 GUI).
3551 Note: When input() is called from within a mapping it will
3552 consume remaining characters from that mapping, because a
3553 mapping is handled like the characters were typed.
3554 Use |inputsave()| before input() and |inputrestore()|
3555 after input() to avoid that. Another solution is to avoid
3556 that further characters follow in the mapping, e.g., by using
3557 |:execute| or |:normal|.
3559 Example with a mapping: >
3560 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR>
3563 : let g:Foo = input("enter search pattern: ")
3564 : call inputrestore()
3567 inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
3568 Like |input()|, but when the GUI is running and text dialogs
3569 are supported, a dialog window pops up to input the text.
3571 :let n = inputdialog("value for shiftwidth", &sw)
3575 < When the dialog is cancelled {cancelreturn} is returned. When
3576 omitted an empty string is returned.
3577 Hitting <Enter> works like pressing the OK button. Hitting
3578 <Esc> works like pressing the Cancel button.
3579 NOTE: Command-line completion is not supported.
3581 inputlist({textlist}) *inputlist()*
3582 {textlist} must be a |List| of strings. This |List| is
3583 displayed, one string per line. The user will be prompted to
3584 enter a number, which is returned.
3585 The user can also select an item by clicking on it with the
3586 mouse. For the first string 0 is returned. When clicking
3587 above the first item a negative number is returned. When
3588 clicking on the prompt one more than the length of {textlist}
3590 Make sure {textlist} has less than 'lines' entries, otherwise
3591 it won't work. It's a good idea to put the entry number at
3592 the start of the string. And put a prompt in the first item.
3594 let color = inputlist(['Select color:', '1. red',
3595 \ '2. green', '3. blue'])
3597 inputrestore() *inputrestore()*
3598 Restore typeahead that was saved with a previous |inputsave()|.
3599 Should be called the same number of times inputsave() is
3600 called. Calling it more often is harmless though.
3601 Returns 1 when there is nothing to restore, 0 otherwise.
3603 inputsave() *inputsave()*
3604 Preserve typeahead (also from mappings) and clear it, so that
3605 a following prompt gets input from the user. Should be
3606 followed by a matching inputrestore() after the prompt. Can
3607 be used several times, in which case there must be just as
3608 many inputrestore() calls.
3609 Returns 1 when out of memory, 0 otherwise.
3611 inputsecret({prompt} [, {text}]) *inputsecret()*
3612 This function acts much like the |input()| function with but
3614 a) the user's response will be displayed as a sequence of
3615 asterisks ("*") thereby keeping the entry secret, and
3616 b) the user's response will not be recorded on the input
3618 The result is a String, which is whatever the user actually
3619 typed on the command-line in response to the issued prompt.
3620 NOTE: Command-line completion is not supported.
3622 insert({list}, {item} [, {idx}]) *insert()*
3623 Insert {item} at the start of |List| {list}.
3624 If {idx} is specified insert {item} before the item with index
3625 {idx}. If {idx} is zero it goes before the first item, just
3626 like omitting {idx}. A negative {idx} is also possible, see
3627 |list-index|. -1 inserts just before the last item.
3628 Returns the resulting |List|. Examples: >
3629 :let mylist = insert([2, 3, 5], 1)
3630 :call insert(mylist, 4, -1)
3631 :call insert(mylist, 6, len(mylist))
3632 < The last example can be done simpler with |add()|.
3633 Note that when {item} is a |List| it is inserted as a single
3634 item. Use |extend()| to concatenate |Lists|.
3636 isdirectory({directory}) *isdirectory()*
3637 The result is a Number, which is non-zero when a directory
3638 with the name {directory} exists. If {directory} doesn't
3639 exist, or isn't a directory, the result is FALSE. {directory}
3640 is any expression, which is used as a String.
3642 islocked({expr}) *islocked()* *E786*
3643 The result is a Number, which is non-zero when {expr} is the
3644 name of a locked variable.
3645 {expr} must be the name of a variable, |List| item or
3646 |Dictionary| entry, not the variable itself! Example: >
3647 :let alist = [0, ['a', 'b'], 2, 3]
3649 :echo islocked('alist') " 1
3650 :echo islocked('alist[1]') " 0
3652 < When {expr} is a variable that does not exist you get an error
3653 message. Use |exists()| to check for existence.
3655 items({dict}) *items()*
3656 Return a |List| with all the key-value pairs of {dict}. Each
3657 |List| item is a list with two items: the key of a {dict}
3658 entry and the value of this entry. The |List| is in arbitrary
3662 join({list} [, {sep}]) *join()*
3663 Join the items in {list} together into one String.
3664 When {sep} is specified it is put in between the items. If
3665 {sep} is omitted a single space is used.
3666 Note that {sep} is not added at the end. You might want to
3668 let lines = join(mylist, "\n") . "\n"
3669 < String items are used as-is. |Lists| and |Dictionaries| are
3670 converted into a string like with |string()|.
3671 The opposite function is |split()|.
3673 keys({dict}) *keys()*
3674 Return a |List| with all the keys of {dict}. The |List| is in
3678 len({expr}) The result is a Number, which is the length of the argument.
3679 When {expr} is a String or a Number the length in bytes is
3680 used, as with |strlen()|.
3681 When {expr} is a |List| the number of items in the |List| is
3683 When {expr} is a |Dictionary| the number of entries in the
3684 |Dictionary| is returned.
3685 Otherwise an error is given.
3687 *libcall()* *E364* *E368*
3688 libcall({libname}, {funcname}, {argument})
3689 Call function {funcname} in the run-time library {libname}
3690 with single argument {argument}.
3691 This is useful to call functions in a library that you
3692 especially made to be used with Vim. Since only one argument
3693 is possible, calling standard library functions is rather
3695 The result is the String returned by the function. If the
3696 function returns NULL, this will appear as an empty string ""
3698 If the function returns a number, use libcallnr()!
3699 If {argument} is a number, it is passed to the function as an
3700 int; if {argument} is a string, it is passed as a
3701 null-terminated string.
3702 This function will fail in |restricted-mode|.
3704 libcall() allows you to write your own 'plug-in' extensions to
3705 Vim without having to recompile the program. It is NOT a
3706 means to call system functions! If you try to do so Vim will
3707 very probably crash.
3709 For Win32, the functions you write must be placed in a DLL
3710 and use the normal C calling convention (NOT Pascal which is
3711 used in Windows System DLLs). The function must take exactly
3712 one parameter, either a character pointer or a long integer,
3713 and must return a character pointer or NULL. The character
3714 pointer returned must point to memory that will remain valid
3715 after the function has returned (e.g. in static data in the
3716 DLL). If it points to allocated memory, that memory will
3717 leak away. Using a static buffer in the function should work,
3718 it's then freed when the DLL is unloaded.
3720 WARNING: If the function returns a non-valid pointer, Vim may
3721 crash! This also happens if the function returns a number,
3722 because Vim thinks it's a pointer.
3723 For Win32 systems, {libname} should be the filename of the DLL
3724 without the ".DLL" suffix. A full path is only required if
3725 the DLL is not in the usual places.
3726 For Unix: When compiling your own plugins, remember that the
3727 object code must be compiled as position-independent ('PIC').
3728 {only in Win32 on some Unix versions, when the |+libcall|
3731 :echo libcall("libc.so", "getenv", "HOME")
3734 libcallnr({libname}, {funcname}, {argument})
3735 Just like |libcall()|, but used for a function that returns an
3736 int instead of a string.
3737 {only in Win32 on some Unix versions, when the |+libcall|
3740 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
3741 :call libcallnr("libc.so", "printf", "Hello World!\n")
3742 :call libcallnr("libc.so", "sleep", 10)
3745 line({expr}) The result is a Number, which is the line number of the file
3746 position given with {expr}. The accepted positions are:
3747 . the cursor position
3748 $ the last line in the current buffer
3749 'x position of mark x (if the mark is not set, 0 is
3751 w0 first line visible in current window
3752 w$ last line visible in current window
3753 v In Visual mode: the start of the Visual area (the
3754 cursor is the end). When not in Visual mode
3755 returns the cursor position. Differs from |'<| in
3756 that it's updated right away.
3757 Note that a mark in another file can be used. The line number
3758 then applies to another buffer.
3759 To get the column number use |col()|. To get both use
3762 line(".") line number of the cursor
3763 line("'t") line number of mark t
3764 line("'" . marker) line number of mark marker
3765 < *last-position-jump*
3766 This autocommand jumps to the last known position in a file
3767 just after opening it, if the '" mark is set: >
3768 :au BufReadPost * if line("'\"") > 1 && line("'\"") <= line("$") | exe "normal! g'\"" | endif
3770 line2byte({lnum}) *line2byte()*
3771 Return the byte count from the start of the buffer for line
3772 {lnum}. This includes the end-of-line character, depending on
3773 the 'fileformat' option for the current buffer. The first
3775 This can also be used to get the byte count for the line just
3776 below the last line: >
3777 line2byte(line("$") + 1)
3778 < This is the file size plus one.
3779 When {lnum} is invalid, or the |+byte_offset| feature has been
3780 disabled at compile time, -1 is returned.
3781 Also see |byte2line()|, |go| and |:goto|.
3783 lispindent({lnum}) *lispindent()*
3784 Get the amount of indent for line {lnum} according the lisp
3785 indenting rules, as with 'lisp'.
3786 The indent is counted in spaces, the value of 'tabstop' is
3787 relevant. {lnum} is used just like in |getline()|.
3788 When {lnum} is invalid or Vim was not compiled the
3789 |+lispindent| feature, -1 is returned.
3791 localtime() *localtime()*
3792 Return the current time, measured as seconds since 1st Jan
3793 1970. See also |strftime()| and |getftime()|.
3796 log10({expr}) *log10()*
3797 Return the logarithm of Float {expr} to base 10 as a |Float|.
3798 {expr} must evaluate to a |Float| or a |Number|.
3804 {only available when compiled with the |+float| feature}
3806 map({expr}, {string}) *map()*
3807 {expr} must be a |List| or a |Dictionary|.
3808 Replace each item in {expr} with the result of evaluating
3810 Inside {string} |v:val| has the value of the current item.
3811 For a |Dictionary| |v:key| has the key of the current item.
3813 :call map(mylist, '"> " . v:val . " <"')
3814 < This puts "> " before and " <" after each item in "mylist".
3816 Note that {string} is the result of an expression and is then
3817 used as an expression again. Often it is good to use a
3818 |literal-string| to avoid having to double backslashes. You
3819 still have to double ' quotes
3821 The operation is done in-place. If you want a |List| or
3822 |Dictionary| to remain unmodified make a copy first: >
3823 :let tlist = map(copy(mylist), ' & . "\t"')
3825 < Returns {expr}, the |List| or |Dictionary| that was filtered.
3826 When an error is encountered while evaluating {string} no
3827 further items in {expr} are processed.
3830 maparg({name}[, {mode} [, {abbr}]]) *maparg()*
3831 Return the rhs of mapping {name} in mode {mode}. When there
3832 is no mapping for {name}, an empty String is returned.
3833 {mode} can be one of these strings:
3836 "o" Operator-pending
3839 "l" langmap |language-mapping|
3840 "" Normal, Visual and Operator-pending
3841 When {mode} is omitted, the modes for "" are used.
3842 When {abbr} is there and it is non-zero use abbreviations
3843 instead of mappings.
3844 The {name} can have special key names, like in the ":map"
3845 command. The returned String has special characters
3846 translated like in the output of the ":map" command listing.
3847 The mappings local to the current buffer are checked first,
3848 then the global mappings.
3849 This function can be used to map a key even when it's already
3850 mapped, and have it do the original mapping too. Sketch: >
3851 exe 'nnoremap <Tab> ==' . maparg('<Tab>', 'n')
3854 mapcheck({name}[, {mode} [, {abbr}]]) *mapcheck()*
3855 Check if there is a mapping that matches with {name} in mode
3856 {mode}. See |maparg()| for {mode} and special names in
3858 When {abbr} is there and it is non-zero use abbreviations
3859 instead of mappings.
3860 A match happens with a mapping that starts with {name} and
3861 with a mapping which is equal to the start of {name}.
3863 matches mapping "a" "ab" "abc" ~
3864 mapcheck("a") yes yes yes
3865 mapcheck("abc") yes yes yes
3866 mapcheck("ax") yes no no
3867 mapcheck("b") no no no
3869 The difference with maparg() is that mapcheck() finds a
3870 mapping that matches with {name}, while maparg() only finds a
3871 mapping for {name} exactly.
3872 When there is no mapping that starts with {name}, an empty
3873 String is returned. If there is one, the rhs of that mapping
3874 is returned. If there are several mappings that start with
3875 {name}, the rhs of one of them is returned.
3876 The mappings local to the current buffer are checked first,
3877 then the global mappings.
3878 This function can be used to check if a mapping can be added
3879 without being ambiguous. Example: >
3880 :if mapcheck("_vv") == ""
3881 : map _vv :set guifont=7x13<CR>
3883 < This avoids adding the "_vv" mapping when there already is a
3884 mapping for "_v" or for "_vvv".
3886 match({expr}, {pat}[, {start}[, {count}]]) *match()*
3887 When {expr} is a |List| then this returns the index of the
3888 first item where {pat} matches. Each item is used as a
3889 String, |Lists| and |Dictionaries| are used as echoed.
3890 Otherwise, {expr} is used as a String. The result is a
3891 Number, which gives the index (byte offset) in {expr} where
3893 A match at the first character or |List| item returns zero.
3894 If there is no match -1 is returned.
3896 :echo match("testing", "ing") " results in 4
3897 :echo match([1, 'x'], '\a') " results in 1
3898 < See |string-match| for how {pat} is used.
3900 Vim doesn't have a strpbrk() function. But you can do: >
3901 :let sepidx = match(line, '[.,;: \t]')
3903 Vim doesn't have a strcasestr() function. But you can add
3904 "\c" to the pattern to ignore case: >
3905 :let idx = match(haystack, '\cneedle')
3907 If {start} is given, the search starts from byte index
3908 {start} in a String or item {start} in a |List|.
3909 The result, however, is still the index counted from the
3910 first character/item. Example: >
3911 :echo match("testing", "ing", 2)
3912 < result is again "4". >
3913 :echo match("testing", "ing", 4)
3914 < result is again "4". >
3915 :echo match("testing", "t", 2)
3917 For a String, if {start} > 0 then it is like the string starts
3918 {start} bytes later, thus "^" will match at {start}. Except
3919 when {count} is given, then it's like matches before the
3920 {start} byte are ignored (this is a bit complicated to keep it
3921 backwards compatible).
3922 For a String, if {start} < 0, it will be set to 0. For a list
3923 the index is counted from the end.
3924 If {start} is out of range ({start} > strlen({expr}) for a
3925 String or {start} > len({expr}) for a |List|) -1 is returned.
3927 When {count} is given use the {count}'th match. When a match
3928 is found in a String the search for the next one starts one
3929 character further. Thus this example results in 1: >
3930 echo match("testing", "..", 0, 2)
3931 < In a |List| the search continues in the next item.
3932 Note that when {count} is added the way {start} works changes,
3935 See |pattern| for the patterns that are accepted.
3936 The 'ignorecase' option is used to set the ignore-caseness of
3937 the pattern. 'smartcase' is NOT used. The matching is always
3938 done like 'magic' is set and 'cpoptions' is empty.
3940 *matchadd()* *E798* *E799* *E801*
3941 matchadd({group}, {pattern}[, {priority}[, {id}]])
3942 Defines a pattern to be highlighted in the current window (a
3943 "match"). It will be highlighted with {group}. Returns an
3944 identification number (ID), which can be used to delete the
3945 match using |matchdelete()|.
3947 The optional {priority} argument assigns a priority to the
3948 match. A match with a high priority will have its
3949 highlighting overrule that of a match with a lower priority.
3950 A priority is specified as an integer (negative numbers are no
3951 exception). If the {priority} argument is not specified, the
3952 default priority is 10. The priority of 'hlsearch' is zero,
3953 hence all matches with a priority greater than zero will
3954 overrule it. Syntax highlighting (see 'syntax') is a separate
3955 mechanism, and regardless of the chosen priority a match will
3956 always overrule syntax highlighting.
3958 The optional {id} argument allows the request for a specific
3959 match ID. If a specified ID is already taken, an error
3960 message will appear and the match will not be added. An ID
3961 is specified as a positive integer (zero excluded). IDs 1, 2
3962 and 3 are reserved for |:match|, |:2match| and |:3match|,
3963 respectively. If the {id} argument is not specified,
3964 |matchadd()| automatically chooses a free ID.
3966 The number of matches is not limited, as it is the case with
3967 the |:match| commands.
3970 :highlight MyGroup ctermbg=green guibg=green
3971 :let m = matchadd("MyGroup", "TODO")
3972 < Deletion of the pattern: >
3973 :call matchdelete(m)
3975 < A list of matches defined by |matchadd()| and |:match| are
3976 available from |getmatches()|. All matches can be deleted in
3977 one operation by |clearmatches()|.
3979 matcharg({nr}) *matcharg()*
3980 Selects the {nr} match item, as set with a |:match|,
3981 |:2match| or |:3match| command.
3982 Return a |List| with two elements:
3983 The name of the highlight group used
3985 When {nr} is not 1, 2 or 3 returns an empty |List|.
3986 When there is no match item set returns ['', ''].
3987 This is useful to save and restore a |:match|.
3988 Highlighting matches using the |:match| commands are limited
3989 to three matches. |matchadd()| does not have this limitation.
3991 matchdelete({id}) *matchdelete()* *E802* *E803*
3992 Deletes a match with ID {id} previously defined by |matchadd()|
3993 or one of the |:match| commands. Returns 0 if successful,
3994 otherwise -1. See example for |matchadd()|. All matches can
3995 be deleted in one operation by |clearmatches()|.
3997 matchend({expr}, {pat}[, {start}[, {count}]]) *matchend()*
3998 Same as |match()|, but return the index of first character
3999 after the match. Example: >
4000 :echo matchend("testing", "ing")
4002 *strspn()* *strcspn()*
4003 Vim doesn't have a strspn() or strcspn() function, but you can
4004 do it with matchend(): >
4005 :let span = matchend(line, '[a-zA-Z]')
4006 :let span = matchend(line, '[^a-zA-Z]')
4007 < Except that -1 is returned when there are no matches.
4009 The {start}, if given, has the same meaning as for |match()|. >
4010 :echo matchend("testing", "ing", 2)
4012 :echo matchend("testing", "ing", 5)
4014 When {expr} is a |List| the result is equal to |match()|.
4016 matchlist({expr}, {pat}[, {start}[, {count}]]) *matchlist()*
4017 Same as |match()|, but return a |List|. The first item in the
4018 list is the matched string, same as what matchstr() would
4019 return. Following items are submatches, like "\1", "\2", etc.
4020 in |:substitute|. When an optional submatch didn't match an
4021 empty string is used. Example: >
4022 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
4023 < Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
4024 When there is no match an empty list is returned.
4026 matchstr({expr}, {pat}[, {start}[, {count}]]) *matchstr()*
4027 Same as |match()|, but return the matched string. Example: >
4028 :echo matchstr("testing", "ing")
4030 When there is no match "" is returned.
4031 The {start}, if given, has the same meaning as for |match()|. >
4032 :echo matchstr("testing", "ing", 2)
4033 < results in "ing". >
4034 :echo matchstr("testing", "ing", 5)
4036 When {expr} is a |List| then the matching item is returned.
4037 The type isn't changed, it's not necessarily a String.
4040 max({list}) Return the maximum value of all items in {list}.
4041 If {list} is not a list or one of the items in {list} cannot
4042 be used as a Number this results in an error.
4043 An empty |List| results in zero.
4046 min({list}) Return the minimum value of all items in {list}.
4047 If {list} is not a list or one of the items in {list} cannot
4048 be used as a Number this results in an error.
4049 An empty |List| results in zero.
4052 mkdir({name} [, {path} [, {prot}]])
4053 Create directory {name}.
4054 If {path} is "p" then intermediate directories are created as
4055 necessary. Otherwise it must be "".
4056 If {prot} is given it is used to set the protection bits of
4057 the new directory. The default is 0755 (rwxr-xr-x: r/w for
4058 the user readable for others). Use 0700 to make it unreadable
4059 for others. This is only used for the last part of {name}.
4060 Thus if you create /tmp/foo/bar then /tmp/foo will be created
4063 :call mkdir($HOME . "/tmp/foo/bar", "p", 0700)
4064 < This function is not available in the |sandbox|.
4065 Not available on all systems. To check use: >
4066 :if exists("*mkdir")
4069 mode([expr]) Return a string that indicates the current mode.
4070 If [expr] is supplied and it evaluates to a non-zero Number or
4071 a non-empty String (|non-zero-arg|), then the full mode is
4072 returned, otherwise only the first letter is returned. Note
4073 that " " and "0" are also non-empty strings.
4077 v Visual by character
4079 CTRL-V Visual blockwise
4080 s Select by character
4082 CTRL-S Select blockwise
4085 Rv Virtual Replace |gR|
4088 ce Normal Ex mode |Q|
4090 rm The -- more -- prompt
4091 r? A |:confirm| query of some sort
4092 ! Shell or external command is executing
4093 This is useful in the 'statusline' option or when used
4094 with |remote_expr()| In most other places it always returns
4096 Also see |visualmode()|.
4098 nextnonblank({lnum}) *nextnonblank()*
4099 Return the line number of the first line at or below {lnum}
4100 that is not blank. Example: >
4101 if getline(nextnonblank(1)) =~ "Java"
4102 < When {lnum} is invalid or there is no non-blank line at or
4103 below it, zero is returned.
4104 See also |prevnonblank()|.
4106 nr2char({expr}) *nr2char()*
4107 Return a string with a single character, which has the number
4108 value {expr}. Examples: >
4109 nr2char(64) returns "@"
4110 nr2char(32) returns " "
4111 < The current 'encoding' is used. Example for "utf-8": >
4112 nr2char(300) returns I with bow character
4113 < Note that a NUL character in the file is specified with
4114 nr2char(10), because NULs are represented with newline
4115 characters. nr2char(0) is a real NUL and terminates the
4116 string, thus results in an empty string.
4119 getpid() Return a Number which is the process ID of the Vim process.
4120 On Unix and MS-Windows this is a unique number, until Vim
4121 exits. On MS-DOS it's always zero.
4124 getpos({expr}) Get the position for {expr}. For possible values of {expr}
4126 The result is a |List| with four numbers:
4127 [bufnum, lnum, col, off]
4128 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
4129 is the buffer number of the mark.
4130 "lnum" and "col" are the position in the buffer. The first
4132 The "off" number is zero, unless 'virtualedit' is used. Then
4133 it is the offset in screen columns from the start of the
4134 character. E.g., a position within a <Tab> or after the last
4136 This can be used to save and restore the cursor position: >
4137 let save_cursor = getpos(".")
4139 call setpos('.', save_cursor)
4140 < Also see |setpos()|.
4142 pathshorten({expr}) *pathshorten()*
4143 Shorten directory names in the path {expr} and return the
4144 result. The tail, the file name, is kept as-is. The other
4145 components in the path are reduced to single letters. Leading
4146 '~' and '.' characters are kept. Example: >
4147 :echo pathshorten('~/.vim/autoload/myfile.vim')
4148 < ~/.v/a/myfile.vim ~
4149 It doesn't matter if the path exists or not.
4151 pow({x}, {y}) *pow()*
4152 Return the power of {x} to the exponent {y} as a |Float|.
4153 {x} and {y} must evaluate to a |Float| or a |Number|.
4161 {only available when compiled with the |+float| feature}
4163 prevnonblank({lnum}) *prevnonblank()*
4164 Return the line number of the first line at or above {lnum}
4165 that is not blank. Example: >
4166 let ind = indent(prevnonblank(v:lnum - 1))
4167 < When {lnum} is invalid or there is no non-blank line at or
4168 above it, zero is returned.
4169 Also see |nextnonblank()|.
4172 printf({fmt}, {expr1} ...) *printf()*
4173 Return a String with {fmt}, where "%" items are replaced by
4174 the formatted form of their respective arguments. Example: >
4175 printf("%4d: E%d %.30s", lnum, errno, msg)
4177 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
4179 Often used items are:
4181 %6s string right-aligned in 6 bytes
4182 %.9s string truncated to 9 bytes
4185 %5d decimal number padded with spaces to 5 characters
4187 %04x hex number padded with zeros to at least 4 characters
4188 %X hex number using upper case letters
4190 %f floating point number in the form 123.456
4191 %e floating point number in the form 1.234e3
4192 %E floating point number in the form 1.234E3
4193 %g floating point number, as %f or %e depending on value
4194 %G floating point number, as %f or %E depending on value
4195 %% the % character itself
4197 Conversion specifications start with '%' and end with the
4198 conversion type. All other characters are copied unchanged to
4201 The "%" starts a conversion specification. The following
4202 arguments appear in sequence:
4204 % [flags] [field-width] [.precision] type
4207 Zero or more of the following flags:
4209 # The value should be converted to an "alternate
4210 form". For c, d, and s conversions, this option
4211 has no effect. For o conversions, the precision
4212 of the number is increased to force the first
4213 character of the output string to a zero (except
4214 if a zero value is printed with an explicit
4216 For x and X conversions, a non-zero result has
4217 the string "0x" (or "0X" for X conversions)
4220 0 (zero) Zero padding. For all conversions the converted
4221 value is padded on the left with zeros rather
4222 than blanks. If a precision is given with a
4223 numeric conversion (d, o, x, and X), the 0 flag
4226 - A negative field width flag; the converted value
4227 is to be left adjusted on the field boundary.
4228 The converted value is padded on the right with
4229 blanks, rather than on the left with blanks or
4230 zeros. A - overrides a 0 if both are given.
4232 ' ' (space) A blank should be left before a positive
4233 number produced by a signed conversion (d).
4235 + A sign must always be placed before a number
4236 produced by a signed conversion. A + overrides
4237 a space if both are used.
4240 An optional decimal digit string specifying a minimum
4241 field width. If the converted value has fewer bytes
4242 than the field width, it will be padded with spaces on
4243 the left (or right, if the left-adjustment flag has
4244 been given) to fill out the field width.
4247 An optional precision, in the form of a period '.'
4248 followed by an optional digit string. If the digit
4249 string is omitted, the precision is taken as zero.
4250 This gives the minimum number of digits to appear for
4251 d, o, x, and X conversions, or the maximum number of
4252 bytes to be printed from a string for s conversions.
4253 For floating point it is the number of digits after
4257 A character that specifies the type of conversion to
4258 be applied, see below.
4260 A field width or precision, or both, may be indicated by an
4261 asterisk '*' instead of a digit string. In this case, a
4262 Number argument supplies the field width or precision. A
4263 negative field width is treated as a left adjustment flag
4264 followed by a positive field width; a negative precision is
4265 treated as though it were missing. Example: >
4266 :echo printf("%d: %.*s", nr, width, line)
4267 < This limits the length of the text used from "line" to
4270 The conversion specifiers and their meanings are:
4272 *printf-d* *printf-o* *printf-x* *printf-X*
4273 doxX The Number argument is converted to signed decimal
4274 (d), unsigned octal (o), or unsigned hexadecimal (x
4275 and X) notation. The letters "abcdef" are used for
4276 x conversions; the letters "ABCDEF" are used for X
4278 The precision, if any, gives the minimum number of
4279 digits that must appear; if the converted value
4280 requires fewer digits, it is padded on the left with
4282 In no case does a non-existent or small field width
4283 cause truncation of a numeric field; if the result of
4284 a conversion is wider than the field width, the field
4285 is expanded to contain the conversion result.
4288 c The Number argument is converted to a byte, and the
4289 resulting character is written.
4292 s The text of the String argument is used. If a
4293 precision is specified, no more bytes than the number
4297 f The Float argument is converted into a string of the
4298 form 123.456. The precision specifies the number of
4299 digits after the decimal point. When the precision is
4300 zero the decimal point is omitted. When the precision
4301 is not specified 6 is used. A really big number
4302 (out of range or dividing by zero) results in "inf".
4303 "0.0 / 0.0" results in "nan".
4305 echo printf("%.2f", 12.115)
4307 Note that roundoff depends on the system libraries.
4308 Use |round()| when in doubt.
4310 *printf-e* *printf-E*
4311 e E The Float argument is converted into a string of the
4312 form 1.234e+03 or 1.234E+03 when using 'E'. The
4313 precision specifies the number of digits after the
4314 decimal point, like with 'f'.
4316 *printf-g* *printf-G*
4317 g G The Float argument is converted like with 'f' if the
4318 value is between 0.001 (inclusive) and 10000000.0
4319 (exclusive). Otherwise 'e' is used for 'g' and 'E'
4320 for 'G'. When no precision is specified superfluous
4321 zeroes and '+' signs are removed, except for the zero
4322 immediately after the decimal point. Thus 10000000.0
4326 % A '%' is written. No argument is converted. The
4327 complete conversion specification is "%%".
4329 When a Number argument is expected a String argument is also
4330 accepted and automatically converted.
4331 When a Float or String argument is expected a Number argument
4332 is also accepted and automatically converted.
4333 Any other argument type results in an error message.
4336 The number of {exprN} arguments must exactly match the number
4337 of "%" items. If there are not sufficient or too many
4338 arguments an error is given. Up to 18 arguments can be used.
4341 pumvisible() *pumvisible()*
4342 Returns non-zero when the popup menu is visible, zero
4343 otherwise. See |ins-completion-menu|.
4344 This can be used to avoid some things that would remove the
4348 range({expr} [, {max} [, {stride}]]) *range()*
4349 Returns a |List| with Numbers:
4350 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
4351 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
4352 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
4353 {max}] (increasing {expr} with {stride} each time, not
4354 producing a value past {max}).
4355 When the maximum is one before the start the result is an
4356 empty list. When the maximum is more than one before the
4357 start this is an error.
4359 range(4) " [0, 1, 2, 3]
4360 range(2, 4) " [2, 3, 4]
4361 range(2, 9, 3) " [2, 5, 8]
4362 range(2, -2, -1) " [2, 1, 0, -1, -2]
4364 range(2, 0) " error!
4367 readfile({fname} [, {binary} [, {max}]])
4368 Read file {fname} and return a |List|, each line of the file
4369 as an item. Lines broken at NL characters. Macintosh files
4370 separated with CR will result in a single long line (unless a
4371 NL appears somewhere).
4372 When {binary} is equal to "b" binary mode is used:
4373 - When the last line ends in a NL an extra empty list item is
4375 - No CR characters are removed.
4377 - CR characters that appear before a NL are removed.
4378 - Whether the last line ends in a NL or not does not matter.
4379 All NUL characters are replaced with a NL character.
4380 When {max} is given this specifies the maximum number of lines
4381 to be read. Useful if you only want to check the first ten
4383 :for line in readfile(fname, '', 10)
4384 : if line =~ 'Date' | echo line | endif
4386 < When {max} is negative -{max} lines from the end of the file
4387 are returned, or as many as there are.
4388 When {max} is zero the result is an empty list.
4389 Note that without {max} the whole file is read into memory.
4390 Also note that there is no recognition of encoding. Read a
4391 file into a buffer if you need to.
4392 When the file can't be opened an error message is given and
4393 the result is an empty list.
4394 Also see |writefile()|.
4396 reltime([{start} [, {end}]]) *reltime()*
4397 Return an item that represents a time value. The format of
4398 the item depends on the system. It can be passed to
4399 |reltimestr()| to convert it to a string.
4400 Without an argument it returns the current time.
4401 With one argument is returns the time passed since the time
4402 specified in the argument.
4403 With two arguments it returns the time passed between {start}
4405 The {start} and {end} arguments must be values returned by
4407 {only available when compiled with the +reltime feature}
4409 reltimestr({time}) *reltimestr()*
4410 Return a String that represents the time value of {time}.
4411 This is the number of seconds, a dot and the number of
4412 microseconds. Example: >
4413 let start = reltime()
4415 echo reltimestr(reltime(start))
4416 < Note that overhead for the commands will be added to the time.
4417 The accuracy depends on the system.
4418 Leading spaces are used to make the string align nicely. You
4419 can use split() to remove it. >
4420 echo split(reltimestr(reltime(start)))[0]
4421 < Also see |profiling|.
4422 {only available when compiled with the +reltime feature}
4424 *remote_expr()* *E449*
4425 remote_expr({server}, {string} [, {idvar}])
4426 Send the {string} to {server}. The string is sent as an
4427 expression and the result is returned after evaluation.
4428 The result must be a String or a |List|. A |List| is turned
4429 into a String by joining the items with a line break in
4430 between (not at the end), like with join(expr, "\n").
4431 If {idvar} is present, it is taken as the name of a
4432 variable and a {serverid} for later use with
4433 remote_read() is stored there.
4434 See also |clientserver| |RemoteReply|.
4435 This function is not available in the |sandbox|.
4436 {only available when compiled with the |+clientserver| feature}
4437 Note: Any errors will cause a local error message to be issued
4438 and the result will be the empty string.
4440 :echo remote_expr("gvim", "2+2")
4441 :echo remote_expr("gvim1", "b:current_syntax")
4444 remote_foreground({server}) *remote_foreground()*
4445 Move the Vim server with the name {server} to the foreground.
4447 remote_expr({server}, "foreground()")
4448 < Except that on Win32 systems the client does the work, to work
4449 around the problem that the OS doesn't always allow the server
4450 to bring itself to the foreground.
4451 Note: This does not restore the window if it was minimized,
4452 like foreground() does.
4453 This function is not available in the |sandbox|.
4454 {only in the Win32, Athena, Motif and GTK GUI versions and the
4455 Win32 console version}
4458 remote_peek({serverid} [, {retvar}]) *remote_peek()*
4459 Returns a positive number if there are available strings
4460 from {serverid}. Copies any reply string into the variable
4461 {retvar} if specified. {retvar} must be a string with the
4463 Returns zero if none are available.
4464 Returns -1 if something is wrong.
4465 See also |clientserver|.
4466 This function is not available in the |sandbox|.
4467 {only available when compiled with the |+clientserver| feature}
4470 :echo "PEEK: ".remote_peek(id, "repl").": ".repl
4472 remote_read({serverid}) *remote_read()*
4473 Return the oldest available reply from {serverid} and consume
4474 it. It blocks until a reply is available.
4475 See also |clientserver|.
4476 This function is not available in the |sandbox|.
4477 {only available when compiled with the |+clientserver| feature}
4479 :echo remote_read(id)
4481 *remote_send()* *E241*
4482 remote_send({server}, {string} [, {idvar}])
4483 Send the {string} to {server}. The string is sent as input
4484 keys and the function returns immediately. At the Vim server
4485 the keys are not mapped |:map|.
4486 If {idvar} is present, it is taken as the name of a variable
4487 and a {serverid} for later use with remote_read() is stored
4489 See also |clientserver| |RemoteReply|.
4490 This function is not available in the |sandbox|.
4491 {only available when compiled with the |+clientserver| feature}
4492 Note: Any errors will be reported in the server and may mess
4495 :echo remote_send("gvim", ":DropAndReply ".file, "serverid").
4496 \ remote_read(serverid)
4498 :autocmd NONE RemoteReply *
4499 \ echo remote_read(expand("<amatch>"))
4500 :echo remote_send("gvim", ":sleep 10 | echo ".
4501 \ 'server2client(expand("<client>"), "HELLO")<CR>')
4503 remove({list}, {idx} [, {end}]) *remove()*
4504 Without {end}: Remove the item at {idx} from |List| {list} and
4506 With {end}: Remove items from {idx} to {end} (inclusive) and
4507 return a List with these items. When {idx} points to the same
4508 item as {end} a list with one item is returned. When {end}
4509 points to an item before {idx} this is an error.
4510 See |list-index| for possible values of {idx} and {end}.
4512 :echo "last item: " . remove(mylist, -1)
4513 :call remove(mylist, 0, 9)
4514 remove({dict}, {key})
4515 Remove the entry from {dict} with key {key}. Example: >
4516 :echo "removed " . remove(dict, "one")
4517 < If there is no {key} in {dict} this is an error.
4519 Use |delete()| to remove a file.
4521 rename({from}, {to}) *rename()*
4522 Rename the file by the name {from} to the name {to}. This
4523 should also work to move files across file systems. The
4524 result is a Number, which is 0 if the file was renamed
4525 successfully, and non-zero when the renaming failed.
4526 NOTE: If {to} exists it is overwritten without warning.
4527 This function is not available in the |sandbox|.
4529 repeat({expr}, {count}) *repeat()*
4530 Repeat {expr} {count} times and return the concatenated
4532 :let separator = repeat('-', 80)
4533 < When {count} is zero or negative the result is empty.
4534 When {expr} is a |List| the result is {expr} concatenated
4535 {count} times. Example: >
4536 :let longlist = repeat(['a', 'b'], 3)
4537 < Results in ['a', 'b', 'a', 'b', 'a', 'b'].
4540 resolve({filename}) *resolve()* *E655*
4541 On MS-Windows, when {filename} is a shortcut (a .lnk file),
4542 returns the path the shortcut points to in a simplified form.
4543 On Unix, repeat resolving symbolic links in all path
4544 components of {filename} and return the simplified result.
4545 To cope with link cycles, resolving of symbolic links is
4546 stopped after 100 iterations.
4547 On other systems, return the simplified {filename}.
4548 The simplification step is done as by |simplify()|.
4549 resolve() keeps a leading path component specifying the
4550 current directory (provided the result is still a relative
4551 path name) and also keeps a trailing path separator.
4554 reverse({list}) Reverse the order of items in {list} in-place. Returns
4556 If you want a list to remain unmodified make a copy first: >
4557 :let revlist = reverse(copy(mylist))
4559 round({expr}) *round()*
4560 Round off {expr} to the nearest integral value and return it
4561 as a |Float|. If {expr} lies halfway between two integral
4562 values, then use the larger one (away from zero).
4563 {expr} must evaluate to a |Float| or a |Number|.
4571 {only available when compiled with the |+float| feature}
4574 search({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *search()*
4575 Search for regexp pattern {pattern}. The search starts at the
4576 cursor position (you can use |cursor()| to set it).
4578 {flags} is a String, which can contain these character flags:
4579 'b' search backward instead of forward
4580 'c' accept a match at the cursor position
4581 'e' move to the End of the match
4582 'n' do Not move the cursor
4583 'p' return number of matching sub-pattern (see below)
4584 's' set the ' mark at the previous location of the cursor
4585 'w' wrap around the end of the file
4586 'W' don't wrap around the end of the file
4587 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
4589 If the 's' flag is supplied, the ' mark is set, only if the
4590 cursor is moved. The 's' flag cannot be combined with the 'n'
4593 'ignorecase', 'smartcase' and 'magic' are used.
4595 When the {stopline} argument is given then the search stops
4596 after searching this line. This is useful to restrict the
4597 search to a range of lines. Examples: >
4598 let match = search('(', 'b', line("w0"))
4599 let end = search('END', '', line("w$"))
4600 < When {stopline} is used and it is not zero this also implies
4601 that the search does not wrap around the end of the file.
4602 A zero value is equal to not giving the argument.
4604 When the {timeout} argument is given the search stops when
4605 more than this many milli seconds have passed. Thus when
4606 {timeout} is 500 the search stops after half a second.
4607 The value must not be negative. A zero value is like not
4608 giving the argument.
4609 {only available when compiled with the +reltime feature}
4611 If there is no match a 0 is returned and the cursor doesn't
4612 move. No error message is given.
4613 When a match has been found its line number is returned.
4614 *search()-sub-match*
4615 With the 'p' flag the returned value is one more than the
4616 first sub-match in \(\). One if none of them matched but the
4617 whole pattern did match.
4618 To get the column number too use |searchpos()|.
4620 The cursor will be positioned at the match, unless the 'n'
4623 Example (goes over all files in the argument list): >
4625 :while n <= argc() " loop over all files in arglist
4626 : exe "argument " . n
4627 : " start at the last char in the file and wrap for the
4628 : " first search to find match at start of file
4631 : while search("foo", flags) > 0
4635 : update " write the file if modified
4639 Example for using some flags: >
4640 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
4641 < This will search for the keywords "if", "else", and "endif"
4642 under or after the cursor. Because of the 'p' flag, it
4643 returns 1, 2, or 3 depending on which keyword is found, or 0
4644 if the search fails. With the cursor on the first word of the
4646 if (foo == 0) | let foo = foo + 1 | endif ~
4647 the function returns 1. Without the 'c' flag, the function
4648 finds the "endif" and returns 3. The same thing happens
4649 without the 'e' flag if the cursor is on the "f" of "if".
4650 The 'n' flag tells the function not to move the cursor.
4653 searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
4654 Search for the declaration of {name}.
4656 With a non-zero {global} argument it works like |gD|, find
4657 first match in the file. Otherwise it works like |gd|, find
4658 first match in the function.
4660 With a non-zero {thisblock} argument matches in a {} block
4661 that ends before the cursor position are ignored. Avoids
4662 finding variable declarations only valid in another scope.
4664 Moves the cursor to the found match.
4665 Returns zero for success, non-zero for failure.
4667 if searchdecl('myvar') == 0
4672 searchpair({start}, {middle}, {end} [, {flags} [, {skip}
4673 [, {stopline} [, {timeout}]]]])
4674 Search for the match of a nested start-end pair. This can be
4675 used to find the "endif" that matches an "if", while other
4676 if/endif pairs in between are ignored.
4677 The search starts at the cursor. The default is to search
4678 forward, include 'b' in {flags} to search backward.
4679 If a match is found, the cursor is positioned at it and the
4680 line number is returned. If no match is found 0 or -1 is
4681 returned and the cursor doesn't move. No error message is
4684 {start}, {middle} and {end} are patterns, see |pattern|. They
4685 must not contain \( \) pairs. Use of \%( \) is allowed. When
4686 {middle} is not empty, it is found when searching from either
4687 direction, but only when not in a nested start-end pair. A
4689 searchpair('\<if\>', '\<else\>', '\<endif\>')
4690 < By leaving {middle} empty the "else" is skipped.
4692 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
4693 |search()|. Additionally:
4694 'r' Repeat until no more matches found; will find the
4695 outer pair. Implies the 'W' flag.
4696 'm' Return number of matches instead of line number with
4697 the match; will be > 1 when 'r' is used.
4698 Note: it's nearly always a good idea to use the 'W' flag, to
4699 avoid wrapping around the end of the file.
4701 When a match for {start}, {middle} or {end} is found, the
4702 {skip} expression is evaluated with the cursor positioned on
4703 the start of the match. It should return non-zero if this
4704 match is to be skipped. E.g., because it is inside a comment
4706 When {skip} is omitted or empty, every match is accepted.
4707 When evaluating {skip} causes an error the search is aborted
4710 For {stopline} and {timeout} see |search()|.
4712 The value of 'ignorecase' is used. 'magic' is ignored, the
4713 patterns are used like it's on.
4715 The search starts exactly at the cursor. A match with
4716 {start}, {middle} or {end} at the next character, in the
4717 direction of searching, is the first one found. Example: >
4722 < When starting at the "if 2", with the cursor on the "i", and
4723 searching forwards, the "endif 2" is found. When starting on
4724 the character just before the "if 2", the "endif 1" will be
4725 found. That's because the "if 2" will be found first, and
4726 then this is considered to be a nested if/endif from "if 2" to
4728 When searching backwards and {end} is more than one character,
4729 it may be useful to put "\zs" at the end of the pattern, so
4730 that when the cursor is inside a match with the end it finds
4733 Example, to find the "endif" command in a Vim script: >
4735 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
4736 \ 'getline(".") =~ "^\\s*\""')
4738 < The cursor must be at or after the "if" for which a match is
4739 to be found. Note that single-quote strings are used to avoid
4740 having to double the backslashes. The skip expression only
4741 catches comments at the start of a line, not after a command.
4742 Also, a word "en" or "if" halfway a line is considered a
4744 Another example, to search for the matching "{" of a "}": >
4746 :echo searchpair('{', '', '}', 'bW')
4748 < This works when the cursor is at or before the "}" for which a
4749 match is to be found. To reject matches that syntax
4750 highlighting recognized as strings: >
4752 :echo searchpair('{', '', '}', 'bW',
4753 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
4756 searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
4757 [, {stopline} [, {timeout}]]]])
4758 Same as |searchpair()|, but returns a |List| with the line and
4759 column position of the match. The first element of the |List|
4760 is the line number and the second element is the byte index of
4761 the column position of the match. If no match is found,
4764 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
4766 See |match-parens| for a bigger and more useful example.
4768 searchpos({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *searchpos()*
4769 Same as |search()|, but returns a |List| with the line and
4770 column position of the match. The first element of the |List|
4771 is the line number and the second element is the byte index of
4772 the column position of the match. If no match is found,
4775 :let [lnum, col] = searchpos('mypattern', 'n')
4777 < When the 'p' flag is given then there is an extra item with
4778 the sub-pattern match number |search()-sub-match|. Example: >
4779 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
4780 < In this example "submatch" is 2 when a lowercase letter is
4781 found |/\l|, 3 when an uppercase letter is found |/\u|.
4783 server2client( {clientid}, {string}) *server2client()*
4784 Send a reply string to {clientid}. The most recent {clientid}
4785 that sent a string can be retrieved with expand("<client>").
4786 {only available when compiled with the |+clientserver| feature}
4788 This id has to be stored before the next command can be
4789 received. I.e. before returning from the received command and
4790 before calling any commands that waits for input.
4791 See also |clientserver|.
4793 :echo server2client(expand("<client>"), "HELLO")
4795 serverlist() *serverlist()*
4796 Return a list of available server names, one per line.
4797 When there are no servers or the information is not available
4798 an empty string is returned. See also |clientserver|.
4799 {only available when compiled with the |+clientserver| feature}
4803 setbufvar({expr}, {varname}, {val}) *setbufvar()*
4804 Set option or local variable {varname} in buffer {expr} to
4806 This also works for a global or local window option, but it
4807 doesn't work for a global or local window variable.
4808 For a local window option the global value is unchanged.
4809 For the use of {expr}, see |bufname()| above.
4810 Note that the variable name without "b:" must be used.
4812 :call setbufvar(1, "&mod", 1)
4813 :call setbufvar("todo", "myvar", "foobar")
4814 < This function is not available in the |sandbox|.
4816 setcmdpos({pos}) *setcmdpos()*
4817 Set the cursor position in the command line to byte position
4818 {pos}. The first position is 1.
4819 Use |getcmdpos()| to obtain the current position.
4820 Only works while editing the command line, thus you must use
4821 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
4822 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
4823 set after the command line is set to the expression. For
4824 |c_CTRL-R_=| it is set after evaluating the expression but
4825 before inserting the resulting text.
4826 When the number is too big the cursor is put at the end of the
4827 line. A number smaller than one has undefined results.
4828 Returns 0 when successful, 1 when not editing the command
4831 setline({lnum}, {text}) *setline()*
4832 Set line {lnum} of the current buffer to {text}.
4833 {lnum} is used like with |getline()|.
4834 When {lnum} is just below the last line the {text} will be
4835 added as a new line.
4836 If this succeeds, 0 is returned. If this fails (most likely
4837 because {lnum} is invalid) 1 is returned. Example: >
4838 :call setline(5, strftime("%c"))
4839 < When {text} is a |List| then line {lnum} and following lines
4840 will be set to the items in the list. Example: >
4841 :call setline(5, ['aaa', 'bbb', 'ccc'])
4842 < This is equivalent to: >
4843 :for [n, l] in [[5, 6, 7], ['aaa', 'bbb', 'ccc']]
4844 : call setline(n, l)
4846 < Note: The '[ and '] marks are not set.
4848 setloclist({nr}, {list} [, {action}]) *setloclist()*
4849 Create or replace or add to the location list for window {nr}.
4850 When {nr} is zero the current window is used. For a location
4851 list window, the displayed location list is modified. For an
4852 invalid window number {nr}, -1 is returned.
4853 Otherwise, same as |setqflist()|.
4854 Also see |location-list|.
4856 setmatches({list}) *setmatches()*
4857 Restores a list of matches saved by |getmatches()|. Returns 0
4858 if successful, otherwise -1. All current matches are cleared
4859 before the list is restored. See example for |getmatches()|.
4862 setpos({expr}, {list})
4863 Set the position for {expr}. Possible values:
4867 {list} must be a |List| with four numbers:
4868 [bufnum, lnum, col, off]
4870 "bufnum" is the buffer number. Zero can be used for the
4871 current buffer. Setting the cursor is only possible for
4872 the current buffer. To set a mark in another buffer you can
4873 use the |bufnr()| function to turn a file name into a buffer
4875 Does not change the jumplist.
4877 "lnum" and "col" are the position in the buffer. The first
4878 column is 1. Use a zero "lnum" to delete a mark.
4880 The "off" number is only used when 'virtualedit' is set. Then
4881 it is the offset in screen columns from the start of the
4882 character. E.g., a position within a <Tab> or after the last
4885 Returns 0 when the position could be set, -1 otherwise.
4886 An error message is given if {expr} is invalid.
4890 This does not restore the preferred column for moving
4891 vertically. See |winrestview()| for that.
4894 setqflist({list} [, {action}]) *setqflist()*
4895 Create or replace or add to the quickfix list using the items
4896 in {list}. Each item in {list} is a dictionary.
4897 Non-dictionary items in {list} are ignored. Each dictionary
4898 item can contain the following entries:
4900 bufnr buffer number; must be the number of a valid
4902 filename name of a file; only used when "bufnr" is not
4903 present or it is invalid.
4904 lnum line number in the file
4905 pattern search pattern used to locate the error
4907 vcol when non-zero: "col" is visual column
4908 when zero: "col" is byte index
4910 text description of the error
4911 type single-character error type, 'E', 'W', etc.
4913 The "col", "vcol", "nr", "type" and "text" entries are
4914 optional. Either "lnum" or "pattern" entry can be used to
4915 locate a matching error line.
4916 If the "filename" and "bufnr" entries are not present or
4917 neither the "lnum" or "pattern" entries are present, then the
4918 item will not be handled as an error line.
4919 If both "pattern" and "lnum" are present then "pattern" will
4921 Note that the list is not exactly the same as what
4922 |getqflist()| returns.
4924 If {action} is set to 'a', then the items from {list} are
4925 added to the existing quickfix list. If there is no existing
4926 list, then a new list is created. If {action} is set to 'r',
4927 then the items from the current quickfix list are replaced
4928 with the items from {list}. If {action} is not present or is
4929 set to ' ', then a new list is created.
4931 Returns zero for success, -1 for failure.
4933 This function can be used to create a quickfix list
4934 independent of the 'errorformat' setting. Use a command like
4935 ":cc 1" to jump to the first position.
4939 setreg({regname}, {value} [,{options}])
4940 Set the register {regname} to {value}.
4941 If {options} contains "a" or {regname} is upper case,
4942 then the value is appended.
4943 {options} can also contains a register type specification:
4944 "c" or "v" |characterwise| mode
4945 "l" or "V" |linewise| mode
4946 "b" or "<CTRL-V>" |blockwise-visual| mode
4947 If a number immediately follows "b" or "<CTRL-V>" then this is
4948 used as the width of the selection - if it is not specified
4949 then the width of the block is set to the number of characters
4950 in the longest line (counting a <Tab> as 1 character).
4952 If {options} contains no register settings, then the default
4953 is to use character mode unless {value} ends in a <NL>.
4954 Setting the '=' register is not possible.
4955 Returns zero for success, non-zero for failure.
4958 :call setreg(v:register, @*)
4959 :call setreg('*', @%, 'ac')
4960 :call setreg('a', "1\n2\n3", 'b5')
4962 < This example shows using the functions to save and restore a
4964 :let var_a = getreg('a', 1)
4965 :let var_amode = getregtype('a')
4967 :call setreg('a', var_a, var_amode)
4969 < You can also change the type of a register by appending
4971 :call setreg('a', '', 'al')
4973 settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
4974 Set option or local variable {varname} in window {winnr} to
4976 Tabs are numbered starting with one. For the current tabpage
4978 When {winnr} is zero the current window is used.
4979 This also works for a global or local buffer option, but it
4980 doesn't work for a global or local buffer variable.
4981 For a local buffer option the global value is unchanged.
4982 Note that the variable name without "w:" must be used.
4983 Vim briefly goes to the tab page {tabnr}, this may trigger
4984 TabLeave and TabEnter autocommands.
4986 :call settabwinvar(1, 1, "&list", 0)
4987 :call settabwinvar(3, 2, "myvar", "foobar")
4988 < This function is not available in the |sandbox|.
4990 setwinvar({nr}, {varname}, {val}) *setwinvar()*
4991 Like |settabwinvar()| for the current tab page.
4993 :call setwinvar(1, "&list", 0)
4994 :call setwinvar(2, "myvar", "foobar")
4996 shellescape({string} [, {special}]) *shellescape()*
4997 Escape {string} for use as shell command argument.
4998 On MS-Windows and MS-DOS, when 'shellslash' is not set, it
4999 will enclose {string} in double quotes and double all double
5000 quotes within {string}.
5001 For other systems, it will enclose {string} in single quotes
5002 and replace all "'" with "'\''".
5003 When the {special} argument is present and it's a non-zero
5004 Number or a non-empty String (|non-zero-arg|), then special
5005 items such as "!", "%", "#" and "<cword>" will be preceded by
5006 a backslash. This backslash will be removed again by the |:!|
5008 The "!" character will be escaped (again with a |non-zero-arg|
5009 {special}) when 'shell' contains "csh" in the tail. That is
5010 because for csh and tcsh "!" is used for history replacement
5011 even when inside single quotes.
5012 The <NL> character is also escaped. With a |non-zero-arg|
5013 {special} and 'shell' containing "csh" in the tail it's
5014 escaped a second time.
5015 Example of use with a |:!| command: >
5016 :exe '!dir ' . shellescape(expand('<cfile>'), 1)
5017 < This results in a directory listing for the file under the
5018 cursor. Example of use with |system()|: >
5019 :call system("chmod +w -- " . shellescape(expand("%")))
5022 simplify({filename}) *simplify()*
5023 Simplify the file name as much as possible without changing
5024 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
5025 Unix) are not resolved. If the first path component in
5026 {filename} designates the current directory, this will be
5027 valid for the result as well. A trailing path separator is
5030 simplify("./dir/.././/file/") == "./file/"
5031 < Note: The combination "dir/.." is only removed if "dir" is
5032 a searchable directory or does not exist. On Unix, it is also
5033 removed when "dir" is a symbolic link within the same
5034 directory. In order to resolve all the involved symbolic
5035 links before simplifying the path name, use |resolve()|.
5039 Return the sine of {expr}, measured in radians, as a |Float|.
5040 {expr} must evaluate to a |Float| or a |Number|.
5046 {only available when compiled with the |+float| feature}
5049 sort({list} [, {func}]) *sort()* *E702*
5050 Sort the items in {list} in-place. Returns {list}. If you
5051 want a list to remain unmodified make a copy first: >
5052 :let sortedlist = sort(copy(mylist))
5053 < Uses the string representation of each item to sort on.
5054 Numbers sort after Strings, |Lists| after Numbers.
5055 For sorting text in the current buffer use |:sort|.
5056 When {func} is given and it is one then case is ignored.
5057 When {func} is a |Funcref| or a function name, this function
5058 is called to compare items. The function is invoked with two
5059 items as argument and must return zero if they are equal, 1 or
5060 bigger if the first one sorts after the second one, -1 or
5061 smaller if the first one sorts before the second one.
5063 func MyCompare(i1, i2)
5064 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
5066 let sortedlist = sort(mylist, "MyCompare")
5067 < A shorter compare version for this specific simple case, which
5069 func MyCompare(i1, i2)
5075 Return the sound-folded equivalent of {word}. Uses the first
5076 language in 'spelllang' for the current window that supports
5077 soundfolding. 'spell' must be set. When no sound folding is
5078 possible the {word} is returned unmodified.
5079 This can be used for making spelling suggestions. Note that
5080 the method can be quite slow.
5083 spellbadword([{sentence}])
5084 Without argument: The result is the badly spelled word under
5085 or after the cursor. The cursor is moved to the start of the
5086 bad word. When no bad word is found in the cursor line the
5087 result is an empty string and the cursor doesn't move.
5089 With argument: The result is the first word in {sentence} that
5090 is badly spelled. If there are no spelling mistakes the
5091 result is an empty string.
5093 The return value is a list with two items:
5094 - The badly spelled word or an empty string.
5095 - The type of the spelling error:
5096 "bad" spelling mistake
5098 "local" word only valid in another region
5099 "caps" word should start with Capital
5101 echo spellbadword("the quik brown fox")
5104 The spelling information for the current window is used. The
5105 'spell' option must be set and the value of 'spelllang' is
5109 spellsuggest({word} [, {max} [, {capital}]])
5110 Return a |List| with spelling suggestions to replace {word}.
5111 When {max} is given up to this number of suggestions are
5112 returned. Otherwise up to 25 suggestions are returned.
5114 When the {capital} argument is given and it's non-zero only
5115 suggestions with a leading capital will be given. Use this
5116 after a match with 'spellcapcheck'.
5118 {word} can be a badly spelled word followed by other text.
5119 This allows for joining two words that were split. The
5120 suggestions also include the following text, thus you can
5123 {word} may also be a good word. Similar words will then be
5124 returned. {word} itself is not included in the suggestions,
5125 although it may appear capitalized.
5127 The spelling information for the current window is used. The
5128 'spell' option must be set and the values of 'spelllang' and
5129 'spellsuggest' are used.
5132 split({expr} [, {pattern} [, {keepempty}]]) *split()*
5133 Make a |List| out of {expr}. When {pattern} is omitted or
5134 empty each white-separated sequence of characters becomes an
5136 Otherwise the string is split where {pattern} matches,
5137 removing the matched characters.
5138 When the first or last item is empty it is omitted, unless the
5139 {keepempty} argument is given and it's non-zero.
5140 Other empty items are kept when {pattern} matches at least one
5141 character or when {keepempty} is non-zero.
5143 :let words = split(getline('.'), '\W\+')
5144 < To split a string in individual characters: >
5145 :for c in split(mystring, '\zs')
5146 < If you want to keep the separator you can also use '\zs': >
5147 :echo split('abc:def:ghi', ':\zs')
5148 < ['abc:', 'def:', 'ghi'] ~
5149 Splitting a table where the first element can be empty: >
5150 :let items = split(line, ':', 1)
5151 < The opposite function is |join()|.
5154 sqrt({expr}) *sqrt()*
5155 Return the non-negative square root of Float {expr} as a
5157 {expr} must evaluate to a |Float| or a |Number|. When {expr}
5158 is negative the result is NaN (Not a Number).
5164 "nan" may be different, it depends on system libraries.
5165 {only available when compiled with the |+float| feature}
5168 str2float( {expr}) *str2float()*
5169 Convert String {expr} to a Float. This mostly works the same
5170 as when using a floating point number in an expression, see
5171 |floating-point-format|. But it's a bit more permissive.
5172 E.g., "1e40" is accepted, while in an expression you need to
5174 Text after the number is silently ignored.
5175 The decimal point is always '.', no matter what the locale is
5176 set to. A comma ends the number: "12,345.67" is converted to
5177 12.0. You can strip out thousands separators with
5179 let f = str2float(substitute(text, ',', '', 'g'))
5180 < {only available when compiled with the |+float| feature}
5183 str2nr( {expr} [, {base}]) *str2nr()*
5184 Convert string {expr} to a number.
5185 {base} is the conversion base, it can be 8, 10 or 16.
5186 When {base} is omitted base 10 is used. This also means that
5187 a leading zero doesn't cause octal conversion to be used, as
5188 with the default String to Number conversion.
5189 When {base} is 16 a leading "0x" or "0X" is ignored. With a
5190 different base the result will be zero.
5191 Text after the number is silently ignored.
5194 strftime({format} [, {time}]) *strftime()*
5195 The result is a String, which is a formatted date and time, as
5196 specified by the {format} string. The given {time} is used,
5197 or the current time if no time is given. The accepted
5198 {format} depends on your system, thus this is not portable!
5199 See the manual page of the C function strftime() for the
5200 format. The maximum length of the result is 80 characters.
5201 See also |localtime()| and |getftime()|.
5202 The language can be changed with the |:language| command.
5204 :echo strftime("%c") Sun Apr 27 11:49:23 1997
5205 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
5206 :echo strftime("%y%m%d %T") 970427 11:53:55
5207 :echo strftime("%H:%M") 11:55
5208 :echo strftime("%c", getftime("file.c"))
5209 Show mod time of file.c.
5210 < Not available on all systems. To check use: >
5211 :if exists("*strftime")
5213 stridx({haystack}, {needle} [, {start}]) *stridx()*
5214 The result is a Number, which gives the byte index in
5215 {haystack} of the first occurrence of the String {needle}.
5216 If {start} is specified, the search starts at index {start}.
5217 This can be used to find a second match: >
5218 :let comma1 = stridx(line, ",")
5219 :let comma2 = stridx(line, ",", comma1 + 1)
5220 < The search is done case-sensitive.
5221 For pattern searches use |match()|.
5222 -1 is returned if the {needle} does not occur in {haystack}.
5223 See also |strridx()|.
5225 :echo stridx("An Example", "Example") 3
5226 :echo stridx("Starting point", "Start") 0
5227 :echo stridx("Starting point", "start") -1
5228 < *strstr()* *strchr()*
5229 stridx() works similar to the C function strstr(). When used
5230 with a single character it works similar to strchr().
5233 string({expr}) Return {expr} converted to a String. If {expr} is a Number,
5234 Float, String or a composition of them, then the result can be
5235 parsed back with |eval()|.
5236 {expr} type result ~
5239 Float 123.123456 or 1.123456e8
5240 Funcref function('name')
5242 Dictionary {key: value, key: value}
5243 Note that in String values the ' character is doubled.
5244 Also see |strtrans()|.
5247 strlen({expr}) The result is a Number, which is the length of the String
5249 If you want to count the number of multi-byte characters (not
5250 counting composing characters) use something like this: >
5252 :let len = strlen(substitute(str, ".", "x", "g"))
5254 If the argument is a Number it is first converted to a String.
5255 For other types an error is given.
5258 strpart({src}, {start}[, {len}]) *strpart()*
5259 The result is a String, which is part of {src}, starting from
5260 byte {start}, with the byte length {len}.
5261 When non-existing bytes are included, this doesn't result in
5262 an error, the bytes are simply omitted.
5263 If {len} is missing, the copy continues from {start} till the
5265 strpart("abcdefg", 3, 2) == "de"
5266 strpart("abcdefg", -2, 4) == "ab"
5267 strpart("abcdefg", 5, 4) == "fg"
5268 strpart("abcdefg", 3) == "defg"
5269 < Note: To get the first character, {start} must be 0. For
5270 example, to get three bytes under and after the cursor: >
5271 strpart(getline("."), col(".") - 1, 3)
5273 strridx({haystack}, {needle} [, {start}]) *strridx()*
5274 The result is a Number, which gives the byte index in
5275 {haystack} of the last occurrence of the String {needle}.
5276 When {start} is specified, matches beyond this index are
5277 ignored. This can be used to find a match before a previous
5279 :let lastcomma = strridx(line, ",")
5280 :let comma2 = strridx(line, ",", lastcomma - 1)
5281 < The search is done case-sensitive.
5282 For pattern searches use |match()|.
5283 -1 is returned if the {needle} does not occur in {haystack}.
5284 If the {needle} is empty the length of {haystack} is returned.
5285 See also |stridx()|. Examples: >
5286 :echo strridx("an angry armadillo", "an") 3
5288 When used with a single character it works similar to the C
5291 strtrans({expr}) *strtrans()*
5292 The result is a String, which is {expr} with all unprintable
5293 characters translated into printable characters |'isprint'|.
5294 Like they are shown in a window. Example: >
5296 < This displays a newline in register a as "^@" instead of
5297 starting a new line.
5299 submatch({nr}) *submatch()*
5300 Only for an expression in a |:substitute| command. Returns
5301 the {nr}'th submatch of the matched text. When {nr} is 0
5302 the whole matched text is returned.
5304 :s/\d\+/\=submatch(0) + 1/
5305 < This finds the first number in the line and adds one to it.
5306 A line break is included as a newline character.
5308 substitute({expr}, {pat}, {sub}, {flags}) *substitute()*
5309 The result is a String, which is a copy of {expr}, in which
5310 the first match of {pat} is replaced with {sub}. This works
5311 like the ":substitute" command (without any flags). But the
5312 matching with {pat} is always done like the 'magic' option is
5313 set and 'cpoptions' is empty (to make scripts portable).
5314 'ignorecase' is still relevant. 'smartcase' is not used.
5315 See |string-match| for how {pat} is used.
5316 And a "~" in {sub} is not replaced with the previous {sub}.
5317 Note that some codes in {sub} have a special meaning
5318 |sub-replace-special|. For example, to replace something with
5319 "\n" (two characters), use "\\\\n" or '\\n'.
5320 When {pat} does not match in {expr}, {expr} is returned
5322 When {flags} is "g", all matches of {pat} in {expr} are
5323 replaced. Otherwise {flags} should be "".
5325 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
5326 < This removes the last component of the 'path' option. >
5327 :echo substitute("testing", ".*", "\\U\\0", "")
5328 < results in "TESTING".
5330 synID({lnum}, {col}, {trans}) *synID()*
5331 The result is a Number, which is the syntax ID at the position
5332 {lnum} and {col} in the current window.
5333 The syntax ID can be used with |synIDattr()| and
5334 |synIDtrans()| to obtain syntax information about text.
5336 {col} is 1 for the leftmost column, {lnum} is 1 for the first
5337 line. 'synmaxcol' applies, in a longer line zero is returned.
5339 When {trans} is non-zero, transparent items are reduced to the
5340 item that they reveal. This is useful when wanting to know
5341 the effective color. When {trans} is zero, the transparent
5342 item is returned. This is useful when wanting to know which
5343 syntax item is effective (e.g. inside parens).
5344 Warning: This function can be very slow. Best speed is
5345 obtained by going through the file in forward direction.
5347 Example (echoes the name of the syntax item under the cursor): >
5348 :echo synIDattr(synID(line("."), col("."), 1), "name")
5350 synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
5351 The result is a String, which is the {what} attribute of
5352 syntax ID {synID}. This can be used to obtain information
5353 about a syntax item.
5354 {mode} can be "gui", "cterm" or "term", to get the attributes
5355 for that mode. When {mode} is omitted, or an invalid value is
5356 used, the attributes for the currently active highlighting are
5357 used (GUI, cterm or term).
5358 Use synIDtrans() to follow linked highlight groups.
5360 "name" the name of the syntax item
5361 "fg" foreground color (GUI: color name used to set
5362 the color, cterm: color number as a string,
5364 "bg" background color (as with "fg")
5365 "sp" special color (as with "fg") |highlight-guisp|
5366 "fg#" like "fg", but for the GUI and the GUI is
5367 running the name in "#RRGGBB" form
5368 "bg#" like "fg#" for "bg"
5369 "sp#" like "fg#" for "sp"
5371 "italic" "1" if italic
5372 "reverse" "1" if reverse
5373 "inverse" "1" if inverse (= reverse)
5374 "underline" "1" if underlined
5375 "undercurl" "1" if undercurled
5377 Example (echoes the color of the syntax item under the
5379 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
5381 synIDtrans({synID}) *synIDtrans()*
5382 The result is a Number, which is the translated syntax ID of
5383 {synID}. This is the syntax group ID of what is being used to
5384 highlight the character. Highlight links given with
5385 ":highlight link" are followed.
5387 synstack({lnum}, {col}) *synstack()*
5388 Return a |List|, which is the stack of syntax items at the
5389 position {lnum} and {col} in the current window. Each item in
5390 the List is an ID like what |synID()| returns.
5391 The first item in the List is the outer region, following are
5392 items contained in that one. The last one is what |synID()|
5393 returns, unless not the whole item is highlighted or it is a
5395 This function is useful for debugging a syntax file.
5396 Example that shows the syntax stack under the cursor: >
5397 for id in synstack(line("."), col("."))
5398 echo synIDattr(id, "name")
5401 system({expr} [, {input}]) *system()* *E677*
5402 Get the output of the shell command {expr}.
5403 When {input} is given, this string is written to a file and
5404 passed as stdin to the command. The string is written as-is,
5405 you need to take care of using the correct line separators
5406 yourself. Pipes are not used.
5407 Note: Use |shellescape()| to escape special characters in a
5408 command argument. Newlines in {expr} may cause the command to
5409 fail. The characters in 'shellquote' and 'shellxquote' may
5411 This is not to be used for interactive commands.
5413 The result is a String. Example: >
5414 :let files = system("ls " . shellescape(expand('%:h')))
5416 < To make the result more system-independent, the shell output
5417 is filtered to replace <CR> with <NL> for Macintosh, and
5418 <CR><NL> with <NL> for DOS-like systems.
5419 The command executed is constructed using several options:
5420 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
5421 ({tmp} is an automatically generated file name).
5422 For Unix and OS/2 braces are put around {expr} to allow for
5423 concatenated commands.
5425 The command will be executed in "cooked" mode, so that a
5426 CTRL-C will interrupt the command (on Unix at least).
5428 The resulting error code can be found in |v:shell_error|.
5429 This function will fail in |restricted-mode|.
5431 Note that any wrong value in the options mentioned above may
5432 make the function fail. It has also been reported to fail
5433 when using a security agent application.
5434 Unlike ":!cmd" there is no automatic check for changed files.
5435 Use |:checktime| to force a check.
5438 tabpagebuflist([{arg}]) *tabpagebuflist()*
5439 The result is a |List|, where each item is the number of the
5440 buffer associated with each window in the current tab page.
5441 {arg} specifies the number of tab page to be used. When
5442 omitted the current tab page is used.
5443 When {arg} is invalid the number zero is returned.
5444 To get a list of all buffers in all tabs use this: >
5446 for i in range(tabpagenr('$'))
5447 call extend(tablist, tabpagebuflist(i + 1))
5449 < Note that a buffer may appear in more than one window.
5452 tabpagenr([{arg}]) *tabpagenr()*
5453 The result is a Number, which is the number of the current
5454 tab page. The first tab page has number 1.
5455 When the optional argument is "$", the number of the last tab
5456 page is returned (the tab page count).
5457 The number can be used with the |:tab| command.
5460 tabpagewinnr({tabarg}, [{arg}]) *tabpagewinnr()*
5461 Like |winnr()| but for tab page {arg}.
5462 {tabarg} specifies the number of tab page to be used.
5463 {arg} is used like with |winnr()|:
5464 - When omitted the current window number is returned. This is
5465 the window which will be used when going to this tab page.
5466 - When "$" the number of windows is returned.
5467 - When "#" the previous window nr is returned.
5469 tabpagewinnr(1) " current window of tab page 1
5470 tabpagewinnr(4, '$') " number of windows in tab page 4
5471 < When {tabarg} is invalid zero is returned.
5474 tagfiles() Returns a |List| with the file names used to search for tags
5475 for the current buffer. This is the 'tags' option expanded.
5478 taglist({expr}) *taglist()*
5479 Returns a list of tags matching the regular expression {expr}.
5480 Each list item is a dictionary with at least the following
5482 name Name of the tag.
5483 filename Name of the file where the tag is
5484 defined. It is either relative to the
5485 current directory or a full path.
5486 cmd Ex command used to locate the tag in
5488 kind Type of the tag. The value for this
5489 entry depends on the language specific
5490 kind values. Only available when
5491 using a tags file generated by
5492 Exuberant ctags or hdrtag.
5493 static A file specific tag. Refer to
5494 |static-tag| for more information.
5495 More entries may be present, depending on the content of the
5496 tags file: access, implementation, inherits and signature.
5497 Refer to the ctags documentation for information about these
5498 fields. For C code the fields "struct", "class" and "enum"
5499 may appear, they give the name of the entity the tag is
5502 The ex-command 'cmd' can be either an ex search pattern, a
5503 line number or a line number followed by a byte number.
5505 If there are no matching tags, then an empty list is returned.
5507 To get an exact tag match, the anchors '^' and '$' should be
5508 used in {expr}. Refer to |tag-regexp| for more information
5509 about the tag search regular expression pattern.
5511 Refer to |'tags'| for information about how the tags file is
5512 located by Vim. Refer to |tags-file-format| for the format of
5513 the tags file generated by the different ctags tools.
5515 tempname() *tempname()* *temp-file-name*
5516 The result is a String, which is the name of a file that
5517 doesn't exist. It can be used for a temporary file. The name
5518 is different for at least 26 consecutive calls. Example: >
5519 :let tmpfile = tempname()
5520 :exe "redir > " . tmpfile
5521 < For Unix, the file will be in a private directory (only
5522 accessible by the current user) to avoid security problems
5523 (e.g., a symlink attack or other people reading your file).
5524 When Vim exits the directory and all files in it are deleted.
5525 For MS-Windows forward slashes are used when the 'shellslash'
5526 option is set or when 'shellcmdflag' starts with '-'.
5528 tolower({expr}) *tolower()*
5529 The result is a copy of the String given, with all uppercase
5530 characters turned into lowercase (just like applying |gu| to
5533 toupper({expr}) *toupper()*
5534 The result is a copy of the String given, with all lowercase
5535 characters turned into uppercase (just like applying |gU| to
5538 tr({src}, {fromstr}, {tostr}) *tr()*
5539 The result is a copy of the {src} string with all characters
5540 which appear in {fromstr} replaced by the character in that
5541 position in the {tostr} string. Thus the first character in
5542 {fromstr} is translated into the first character in {tostr}
5543 and so on. Exactly like the unix "tr" command.
5544 This code also deals with multibyte characters properly.
5547 echo tr("hello there", "ht", "HT")
5548 < returns "Hello THere" >
5549 echo tr("<blob>", "<>", "{}")
5552 trunc({expr}) *trunc()*
5553 Return the largest integral value with magnitude less than or
5554 equal to {expr} as a |Float| (truncate towards zero).
5555 {expr} must evaluate to a |Float| or a |Number|.
5563 {only available when compiled with the |+float| feature}
5566 type({expr}) The result is a Number, depending on the type of {expr}:
5573 To avoid the magic numbers it should be used this way: >
5574 :if type(myvar) == type(0)
5575 :if type(myvar) == type("")
5576 :if type(myvar) == type(function("tr"))
5577 :if type(myvar) == type([])
5578 :if type(myvar) == type({})
5579 :if type(myvar) == type(0.0)
5581 values({dict}) *values()*
5582 Return a |List| with all the values of {dict}. The |List| is
5586 virtcol({expr}) *virtcol()*
5587 The result is a Number, which is the screen column of the file
5588 position given with {expr}. That is, the last screen position
5589 occupied by the character at that position, when the screen
5590 would be of unlimited width. When there is a <Tab> at the
5591 position, the returned Number will be the column at the end of
5592 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
5593 set to 8, it returns 8.
5594 For the byte position use |col()|.
5595 For the use of {expr} see |col()|.
5596 When 'virtualedit' is used {expr} can be [lnum, col, off], where
5597 "off" is the offset in screen columns from the start of the
5598 character. E.g., a position within a <Tab> or after the last
5600 When Virtual editing is active in the current mode, a position
5601 beyond the end of the line can be returned. |'virtualedit'|
5602 The accepted positions are:
5603 . the cursor position
5604 $ the end of the cursor line (the result is the
5605 number of displayed characters in the cursor line
5607 'x position of mark x (if the mark is not set, 0 is
5609 Note that only marks in the current file can be used.
5611 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
5612 virtcol("$") with text "foo^Lbar", returns 9
5613 virtcol("'t") with text " there", with 't at 'h', returns 6
5614 < The first column is 1. 0 is returned for an error.
5615 A more advanced example that echoes the maximum length of
5617 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
5620 visualmode([expr]) *visualmode()*
5621 The result is a String, which describes the last Visual mode
5622 used in the current buffer. Initially it returns an empty
5623 string, but once Visual mode has been used, it returns "v",
5624 "V", or "<CTRL-V>" (a single CTRL-V character) for
5625 character-wise, line-wise, or block-wise Visual mode
5628 :exe "normal " . visualmode()
5629 < This enters the same Visual mode as before. It is also useful
5630 in scripts if you wish to act differently depending on the
5631 Visual mode that was used.
5632 If Visual mode is active, use |mode()| to get the Visual mode
5633 (e.g., in a |:vmap|).
5635 If [expr] is supplied and it evaluates to a non-zero Number or
5636 a non-empty String, then the Visual mode will be cleared and
5637 the old value is returned. Note that " " and "0" are also
5638 non-empty strings, thus cause the mode to be cleared. A List,
5639 Dictionary or Float is not a Number or String, thus does not
5640 cause the mode to be cleared.
5643 winbufnr({nr}) The result is a Number, which is the number of the buffer
5644 associated with window {nr}. When {nr} is zero, the number of
5645 the buffer in the current window is returned. When window
5646 {nr} doesn't exist, -1 is returned.
5648 :echo "The file in the current window is " . bufname(winbufnr(0))
5651 wincol() The result is a Number, which is the virtual column of the
5652 cursor in the window. This is counting screen cells from the
5653 left side of the window. The leftmost column is one.
5655 winheight({nr}) *winheight()*
5656 The result is a Number, which is the height of window {nr}.
5657 When {nr} is zero, the height of the current window is
5658 returned. When window {nr} doesn't exist, -1 is returned.
5659 An existing window always has a height of zero or more.
5661 :echo "The current window has " . winheight(0) . " lines."
5664 winline() The result is a Number, which is the screen line of the cursor
5665 in the window. This is counting screen lines from the top of
5666 the window. The first line is one.
5667 If the cursor was moved the view on the file will be updated
5668 first, this may cause a scroll.
5671 winnr([{arg}]) The result is a Number, which is the number of the current
5672 window. The top window has number 1.
5673 When the optional argument is "$", the number of the
5674 last window is returned (the window count).
5675 When the optional argument is "#", the number of the last
5676 accessed window is returned (where |CTRL-W_p| goes to).
5677 If there is no previous window or it is in another tab page 0
5679 The number can be used with |CTRL-W_w| and ":wincmd w"
5681 Also see |tabpagewinnr()|.
5684 winrestcmd() Returns a sequence of |:resize| commands that should restore
5685 the current window sizes. Only works properly when no windows
5686 are opened or closed and the current window and tab page is
5689 :let cmd = winrestcmd()
5690 :call MessWithWindowSizes()
5695 Uses the |Dictionary| returned by |winsaveview()| to restore
5696 the view of the current window.
5697 If you have changed the values the result is unpredictable.
5698 If the window size changed the result won't be the same.
5701 winsaveview() Returns a |Dictionary| that contains information to restore
5702 the view of the current window. Use |winrestview()| to
5704 This is useful if you have a mapping that jumps around in the
5705 buffer and you want to go back to the original view.
5706 This does not save fold information. Use the 'foldenable'
5707 option to temporarily switch off folding, so that folds are
5708 not opened when moving around.
5709 The return value includes:
5710 lnum cursor line number
5712 coladd cursor column offset for 'virtualedit'
5713 curswant column for vertical movement
5714 topline first line in the window
5715 topfill filler lines, only in diff mode
5716 leftcol first column displayed
5717 skipcol columns skipped
5718 Note that no option values are saved.
5721 winwidth({nr}) *winwidth()*
5722 The result is a Number, which is the width of window {nr}.
5723 When {nr} is zero, the width of the current window is
5724 returned. When window {nr} doesn't exist, -1 is returned.
5725 An existing window always has a width of zero or more.
5727 :echo "The current window has " . winwidth(0) . " columns."
5728 :if winwidth(0) <= 50
5729 : exe "normal 50\<C-W>|"
5733 writefile({list}, {fname} [, {binary}])
5734 Write |List| {list} to file {fname}. Each list item is
5735 separated with a NL. Each list item must be a String or
5737 When {binary} is equal to "b" binary mode is used: There will
5738 not be a NL after the last list item. An empty item at the
5739 end does cause the last line in the file to end in a NL.
5740 All NL characters are replaced with a NUL character.
5741 Inserting CR characters needs to be done before passing {list}
5743 An existing file is overwritten, if possible.
5744 When the write fails -1 is returned, otherwise 0. There is an
5745 error message if the file can't be created or when writing
5747 Also see |readfile()|.
5748 To copy a file byte for byte: >
5749 :let fl = readfile("foo", "b")
5750 :call writefile(fl, "foocopy", "b")
5754 There are three types of features:
5755 1. Features that are only supported when they have been enabled when Vim
5756 was compiled |+feature-list|. Example: >
5758 2. Features that are only supported when certain conditions have been met.
5760 :if has("gui_running")
5762 3. Included patches. First check |v:version| for the version of Vim.
5763 Then the "patch123" feature means that patch 123 has been included for
5764 this version. Example (checking version 6.2.148 or later): >
5765 :if v:version > 602 || v:version == 602 && has("patch148")
5766 < Note that it's possible for patch 147 to be omitted even though 148 is
5769 all_builtin_terms Compiled with all builtin terminals enabled.
5770 amiga Amiga version of Vim.
5771 arabic Compiled with Arabic support |Arabic|.
5772 arp Compiled with ARP support (Amiga).
5773 autocmd Compiled with autocommand support. |autocommand|
5774 balloon_eval Compiled with |balloon-eval| support.
5775 balloon_multiline GUI supports multiline balloons.
5776 beos BeOS version of Vim.
5777 browse Compiled with |:browse| support, and browse() will
5779 builtin_terms Compiled with some builtin terminals.
5780 byte_offset Compiled with support for 'o' in 'statusline'
5781 cindent Compiled with 'cindent' support.
5782 clientserver Compiled with remote invocation support |clientserver|.
5783 clipboard Compiled with 'clipboard' support.
5784 cmdline_compl Compiled with |cmdline-completion| support.
5785 cmdline_hist Compiled with |cmdline-history| support.
5786 cmdline_info Compiled with 'showcmd' and 'ruler' support.
5787 comments Compiled with |'comments'| support.
5788 cryptv Compiled with encryption support |encryption|.
5789 cscope Compiled with |cscope| support.
5790 compatible Compiled to be very Vi compatible.
5791 debug Compiled with "DEBUG" defined.
5792 dialog_con Compiled with console dialog support.
5793 dialog_gui Compiled with GUI dialog support.
5794 diff Compiled with |vimdiff| and 'diff' support.
5795 digraphs Compiled with support for digraphs.
5796 dnd Compiled with support for the "~ register |quote_~|.
5797 dos32 32 bits DOS (DJGPP) version of Vim.
5798 dos16 16 bits DOS version of Vim.
5799 ebcdic Compiled on a machine with ebcdic character set.
5800 emacs_tags Compiled with support for Emacs tags.
5801 eval Compiled with expression evaluation support. Always
5803 ex_extra Compiled with extra Ex commands |+ex_extra|.
5804 extra_search Compiled with support for |'incsearch'| and
5806 farsi Compiled with Farsi support |farsi|.
5807 file_in_path Compiled with support for |gf| and |<cfile>|
5808 filterpipe When 'shelltemp' is off pipes are used for shell
5809 read/write/filter commands
5810 find_in_path Compiled with support for include file searches
5812 float Compiled with support for |Float|.
5813 fname_case Case in file names matters (for Amiga, MS-DOS, and
5814 Windows this is not present).
5815 folding Compiled with |folding| support.
5816 footer Compiled with GUI footer support. |gui-footer|
5817 fork Compiled to use fork()/exec() instead of system().
5818 fullscreen Compiled with 'fullscreen' support.
5819 gettext Compiled with message translation |multi-lang|
5820 gui Compiled with GUI enabled.
5821 gui_athena Compiled with Athena GUI.
5822 gui_gtk Compiled with GTK+ GUI (any version).
5823 gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
5824 gui_gnome Compiled with Gnome support (gui_gtk is also defined).
5825 gui_mac Compiled with Macintosh GUI (Carbon).
5826 gui_macvim Compiled with MacVim GUI.
5827 gui_motif Compiled with Motif GUI.
5828 gui_photon Compiled with Photon GUI.
5829 gui_win32 Compiled with MS Windows Win32 GUI.
5830 gui_win32s idem, and Win32s system being used (Windows 3.1)
5831 gui_running Vim is running in the GUI, or it will start soon.
5832 hangul_input Compiled with Hangul input support. |hangul|
5833 iconv Can use iconv() for conversion.
5834 insert_expand Compiled with support for CTRL-X expansion commands in
5836 jumplist Compiled with |jumplist| support.
5837 keymap Compiled with 'keymap' support.
5838 langmap Compiled with 'langmap' support.
5839 libcall Compiled with |libcall()| support.
5840 linebreak Compiled with 'linebreak', 'breakat' and 'showbreak'
5842 lispindent Compiled with support for lisp indenting.
5843 listcmds Compiled with commands for the buffer list |:files|
5844 and the argument list |arglist|.
5845 localmap Compiled with local mappings and abbr. |:map-local|
5846 mac Macintosh version of Vim.
5847 macunix Macintosh version of Vim, using Unix files (OS-X).
5848 menu Compiled with support for |:menu|.
5849 mksession Compiled with support for |:mksession|.
5850 modify_fname Compiled with file name modifiers. |filename-modifiers|
5851 mouse Compiled with support mouse.
5852 mouseshape Compiled with support for 'mouseshape'.
5853 mouse_dec Compiled with support for Dec terminal mouse.
5854 mouse_gpm Compiled with support for gpm (Linux console mouse)
5855 mouse_netterm Compiled with support for netterm mouse.
5856 mouse_pterm Compiled with support for qnx pterm mouse.
5857 mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
5858 mouse_xterm Compiled with support for xterm mouse.
5859 multi_byte Compiled with support for 'encoding'
5860 multi_byte_encoding 'encoding' is set to a multi-byte encoding.
5861 multi_byte_ime Compiled with support for IME input method.
5862 multi_lang Compiled with support for multiple languages.
5863 mzscheme Compiled with MzScheme interface |mzscheme|.
5864 netbeans_intg Compiled with support for |netbeans|.
5865 netbeans_enabled Compiled with support for |netbeans| and it's used.
5866 odbeditor Compiled with |odbeditor| support.
5867 ole Compiled with OLE automation support for Win32.
5868 os2 OS/2 version of Vim.
5869 osfiletype Compiled with support for osfiletypes |+osfiletype|
5870 path_extra Compiled with up/downwards search in 'path' and 'tags'
5871 perl Compiled with Perl interface.
5872 postscript Compiled with PostScript file printing.
5873 printer Compiled with |:hardcopy| support.
5874 profile Compiled with |:profile| support.
5875 python Compiled with Python interface.
5876 qnx QNX version of Vim.
5877 quickfix Compiled with |quickfix| support.
5878 reltime Compiled with |reltime()| support.
5879 rightleft Compiled with 'rightleft' support.
5880 ruby Compiled with Ruby interface |ruby|.
5881 scrollbind Compiled with 'scrollbind' support.
5882 showcmd Compiled with 'showcmd' support.
5883 signs Compiled with |:sign| support.
5884 smartindent Compiled with 'smartindent' support.
5885 sniff Compiled with SNiFF interface support.
5886 statusline Compiled with support for 'statusline', 'rulerformat'
5887 and special formats of 'titlestring' and 'iconstring'.
5888 sun_workshop Compiled with support for Sun |workshop|.
5889 spell Compiled with spell checking support |spell|.
5890 syntax Compiled with syntax highlighting support |syntax|.
5891 syntax_items There are active syntax highlighting items for the
5893 system Compiled to use system() instead of fork()/exec().
5894 tag_binary Compiled with binary searching in tags files
5895 |tag-binary-search|.
5896 tag_old_static Compiled with support for old static tags
5898 tag_any_white Compiled with support for any white characters in tags
5899 files |tag-any-white|.
5900 tcl Compiled with Tcl interface.
5901 terminfo Compiled with terminfo instead of termcap.
5902 termresponse Compiled with support for |t_RV| and |v:termresponse|.
5903 textobjects Compiled with support for |text-objects|.
5904 tgetent Compiled with tgetent support, able to use a termcap
5906 title Compiled with window title support |'title'|.
5907 toolbar Compiled with support for |gui-toolbar|.
5908 transparency Compiled with 'transparency' support.
5909 unix Unix version of Vim.
5910 user_commands User-defined commands.
5911 viminfo Compiled with viminfo support.
5912 vim_starting True while initial source'ing takes place.
5913 vertsplit Compiled with vertically split windows |:vsplit|.
5914 virtualedit Compiled with 'virtualedit' option.
5915 visual Compiled with Visual mode.
5916 visualextra Compiled with extra Visual mode commands.
5917 |blockwise-operators|.
5918 vms VMS version of Vim.
5919 vreplace Compiled with |gR| and |gr| commands.
5920 wildignore Compiled with 'wildignore' option.
5921 wildmenu Compiled with 'wildmenu' option.
5922 windows Compiled with support for more than one window.
5923 winaltkeys Compiled with 'winaltkeys' option.
5924 win16 Win16 version of Vim (MS-Windows 3.1).
5925 win32 Win32 version of Vim (MS-Windows 95/98/ME/NT/2000/XP).
5926 win64 Win64 version of Vim (MS-Windows 64 bit).
5927 win32unix Win32 version of Vim, using Unix files (Cygwin)
5928 win95 Win32 version for MS-Windows 95/98/ME.
5929 writebackup Compiled with 'writebackup' default on.
5930 xfontset Compiled with X fontset support |xfontset|.
5931 xim Compiled with X input method support |xim|.
5932 xsmp Compiled with X session management support.
5933 xsmp_interact Compiled with interactive X session management support.
5934 xterm_clipboard Compiled with support for xterm clipboard.
5935 xterm_save Compiled with support for saving and restoring the
5937 x11 Compiled with X11 support.
5940 Matching a pattern in a String
5942 A regexp pattern as explained at |pattern| is normally used to find a match in
5943 the buffer lines. When a pattern is used to find a match in a String, almost
5944 everything works in the same way. The difference is that a String is handled
5945 like it is one line. When it contains a "\n" character, this is not seen as a
5946 line break for the pattern. It can be matched with a "\n" in the pattern, or
5947 with ".". Example: >
5948 :let a = "aaaa\nxxxx"
5949 :echo matchstr(a, "..\n..")
5952 :echo matchstr(a, "a.x")
5956 Don't forget that "^" will only match at the first character of the String and
5957 "$" at the last character of the string. They don't match after or before a
5960 ==============================================================================
5961 5. Defining functions *user-functions*
5963 New functions can be defined. These can be called just like builtin
5964 functions. The function executes a sequence of Ex commands. Normal mode
5965 commands can be executed with the |:normal| command.
5967 The function name must start with an uppercase letter, to avoid confusion with
5968 builtin functions. To prevent from using the same name in different scripts
5969 avoid obvious, short names. A good habit is to start the function name with
5970 the name of the script, e.g., "HTMLcolor()".
5972 It's also possible to use curly braces, see |curly-braces-names|. And the
5973 |autoload| facility is useful to define a function only when it's called.
5976 A function local to a script must start with "s:". A local script function
5977 can only be called from within the script and from functions, user commands
5978 and autocommands defined in the script. It is also possible to call the
5979 function from a mapping defined in the script, but then |<SID>| must be used
5980 instead of "s:" when the mapping is expanded outside of the script.
5982 *:fu* *:function* *E128* *E129* *E123*
5983 :fu[nction] List all functions and their arguments.
5985 :fu[nction] {name} List function {name}.
5986 {name} can also be a |Dictionary| entry that is a
5990 :fu[nction] /{pattern} List functions with a name matching {pattern}.
5991 Example that lists all functions ending with "File": >
5995 When 'verbose' is non-zero, listing a function will also display where it was
5996 last defined. Example: >
5998 :verbose function SetFileTypeSH
5999 function SetFileTypeSH(name)
6000 Last set from /usr/share/vim/vim-7.0/filetype.vim
6002 See |:verbose-cmd| for more information.
6005 :fu[nction][!] {name}([arguments]) [range] [abort] [dict]
6006 Define a new function by the name {name}. The name
6007 must be made of alphanumeric characters and '_', and
6008 must start with a capital or "s:" (see above).
6010 {name} can also be a |Dictionary| entry that is a
6012 :function dict.init(arg)
6013 < "dict" must be an existing dictionary. The entry
6014 "init" is added if it didn't exist yet. Otherwise [!]
6015 is required to overwrite an existing function. The
6016 result is a |Funcref| to a numbered function. The
6017 function can only be used with a |Funcref| and will be
6018 deleted if there are no more references to it.
6020 When a function by this name already exists and [!] is
6021 not used an error message is given. When [!] is used,
6022 an existing function is silently replaced. Unless it
6023 is currently being executed, that is an error.
6025 For the {arguments} see |function-argument|.
6027 *a:firstline* *a:lastline*
6028 When the [range] argument is added, the function is
6029 expected to take care of a range itself. The range is
6030 passed as "a:firstline" and "a:lastline". If [range]
6031 is excluded, ":{range}call" will call the function for
6032 each line in the range, with the cursor on the start
6033 of each line. See |function-range-example|.
6035 When the [abort] argument is added, the function will
6036 abort as soon as an error is detected.
6038 When the [dict] argument is added, the function must
6039 be invoked through an entry in a |Dictionary|. The
6040 local variable "self" will then be set to the
6041 dictionary. See |Dictionary-function|.
6043 *function-search-undo*
6044 The last used search pattern and the redo command "."
6045 will not be changed by the function. This also
6046 implies that the effect of |:nohlsearch| is undone
6047 when the function returns.
6049 *:endf* *:endfunction* *E126* *E193*
6050 :endf[unction] The end of a function definition. Must be on a line
6051 by its own, without other commands.
6053 *:delf* *:delfunction* *E130* *E131*
6054 :delf[unction] {name} Delete function {name}.
6055 {name} can also be a |Dictionary| entry that is a
6058 < This will remove the "init" entry from "dict". The
6059 function is deleted if there are no more references to
6061 *:retu* *:return* *E133*
6062 :retu[rn] [expr] Return from a function. When "[expr]" is given, it is
6063 evaluated and returned as the result of the function.
6064 If "[expr]" is not given, the number 0 is returned.
6065 When a function ends without an explicit ":return",
6066 the number 0 is returned.
6067 Note that there is no check for unreachable lines,
6068 thus there is no warning if commands follow ":return".
6070 If the ":return" is used after a |:try| but before the
6071 matching |:finally| (if present), the commands
6072 following the ":finally" up to the matching |:endtry|
6073 are executed first. This process applies to all
6074 nested ":try"s inside the function. The function
6075 returns at the outermost ":endtry".
6077 *function-argument* *a:var*
6078 An argument can be defined by giving its name. In the function this can then
6079 be used as "a:name" ("a:" for argument).
6080 *a:0* *a:1* *a:000* *E740* *...*
6081 Up to 20 arguments can be given, separated by commas. After the named
6082 arguments an argument "..." can be specified, which means that more arguments
6083 may optionally be following. In the function the extra arguments can be used
6084 as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which
6085 can be 0). "a:000" is set to a |List| that contains these arguments. Note
6086 that "a:1" is the same as "a:000[0]".
6088 The a: scope and the variables in it cannot be changed, they are fixed.
6089 However, if a |List| or |Dictionary| is used, you can change their contents.
6090 Thus you can pass a |List| to a function and have the function add an item to
6091 it. If you want to make sure the function cannot change a |List| or
6092 |Dictionary| use |:lockvar|.
6094 When not using "...", the number of arguments in a function call must be equal
6095 to the number of named arguments. When using "...", the number of arguments
6098 It is also possible to define a function without any arguments. You must
6099 still supply the () then. The body of the function follows in the next lines,
6100 until the matching |:endfunction|. It is allowed to define another function
6101 inside a function body.
6104 Inside a function variables can be used. These are local variables, which
6105 will disappear when the function returns. Global variables need to be
6109 :function Table(title, ...)
6113 : echo a:0 . " items:"
6119 This function can then be called with: >
6120 call Table("Table", "line1", "line2")
6121 call Table("Empty Table")
6123 To return more than one value, return a |List|: >
6124 :function Compute(n1, n2)
6126 : return ["fail", 0]
6128 : return ["ok", a:n1 / a:n2]
6131 This function can then be called with: >
6132 :let [success, div] = Compute(102, 6)
6137 *:cal* *:call* *E107* *E117*
6138 :[range]cal[l] {name}([arguments])
6139 Call a function. The name of the function and its arguments
6140 are as specified with |:function|. Up to 20 arguments can be
6141 used. The returned value is discarded.
6142 Without a range and for functions that accept a range, the
6143 function is called once. When a range is given the cursor is
6144 positioned at the start of the first line before executing the
6146 When a range is given and the function doesn't handle it
6147 itself, the function is executed for each line in the range,
6148 with the cursor in the first column of that line. The cursor
6149 is left at the last line (possibly moved by the last function
6150 call). The arguments are re-evaluated for each line. Thus
6152 *function-range-example* >
6153 :function Mynumber(arg)
6154 : echo line(".") . " " . a:arg
6156 :1,5call Mynumber(getline("."))
6158 The "a:firstline" and "a:lastline" are defined anyway, they
6159 can be used to do something different at the start or end of
6162 Example of a function that handles the range itself: >
6164 :function Cont() range
6165 : execute (a:firstline + 1) . "," . a:lastline . 's/^/\t\\ '
6169 This function inserts the continuation character "\" in front
6170 of all the lines in the range, except the first one.
6172 When the function returns a composite value it can be further
6173 dereferenced, but the range will not be used then. Example: >
6174 :4,8call GetDict().method()
6175 < Here GetDict() gets the range but method() does not.
6178 The recursiveness of user functions is restricted with the |'maxfuncdepth'|
6182 AUTOMATICALLY LOADING FUNCTIONS ~
6183 *autoload-functions*
6184 When using many or large functions, it's possible to automatically define them
6185 only when they are used. There are two methods: with an autocommand and with
6186 the "autoload" directory in 'runtimepath'.
6189 Using an autocommand ~
6191 This is introduced in the user manual, section |41.14|.
6193 The autocommand is useful if you have a plugin that is a long Vim script file.
6194 You can define the autocommand and quickly quit the script with |:finish|.
6195 That makes Vim startup faster. The autocommand should then load the same file
6196 again, setting a variable to skip the |:finish| command.
6198 Use the FuncUndefined autocommand event with a pattern that matches the
6199 function(s) to be defined. Example: >
6201 :au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
6203 The file "~/vim/bufnetfuncs.vim" should then define functions that start with
6204 "BufNet". Also see |FuncUndefined|.
6207 Using an autoload script ~
6209 This is introduced in the user manual, section |41.15|.
6211 Using a script in the "autoload" directory is simpler, but requires using
6212 exactly the right file name. A function that can be autoloaded has a name
6215 :call filename#funcname()
6217 When such a function is called, and it is not defined yet, Vim will search the
6218 "autoload" directories in 'runtimepath' for a script file called
6219 "filename.vim". For example "~/.vim/autoload/filename.vim". That file should
6220 then define the function like this: >
6222 function filename#funcname()
6226 The file name and the name used before the # in the function must match
6227 exactly, and the defined function must have the name exactly as it will be
6230 It is possible to use subdirectories. Every # in the function name works like
6231 a path separator. Thus when calling a function: >
6233 :call foo#bar#func()
6235 Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
6237 This also works when reading a variable that has not been set yet: >
6239 :let l = foo#bar#lvar
6241 However, when the autoload script was already loaded it won't be loaded again
6242 for an unknown variable.
6244 When assigning a value to such a variable nothing special happens. This can
6245 be used to pass settings to the autoload script before it's loaded: >
6247 :let foo#bar#toggle = 1
6248 :call foo#bar#func()
6250 Note that when you make a mistake and call a function that is supposed to be
6251 defined in an autoload script, but the script doesn't actually define the
6252 function, the script will be sourced every time you try to call the function.
6253 And you will get an error message every time.
6255 Also note that if you have two script files, and one calls a function in the
6256 other and vice versa, before the used function is defined, it won't work.
6257 Avoid using the autoload functionality at the toplevel.
6259 Hint: If you distribute a bunch of scripts you can pack them together with the
6260 |vimball| utility. Also read the user manual |distribute-script|.
6262 ==============================================================================
6263 6. Curly braces names *curly-braces-names*
6265 Wherever you can use a variable, you can use a "curly braces name" variable.
6266 This is a regular variable name with one or more expressions wrapped in braces
6268 my_{adjective}_variable
6270 When Vim encounters this, it evaluates the expression inside the braces, puts
6271 that in place of the expression, and re-interprets the whole as a variable
6272 name. So in the above example, if the variable "adjective" was set to
6273 "noisy", then the reference would be to "my_noisy_variable", whereas if
6274 "adjective" was set to "quiet", then it would be to "my_quiet_variable".
6276 One application for this is to create a set of variables governed by an option
6277 value. For example, the statement >
6278 echo my_{&background}_message
6280 would output the contents of "my_dark_message" or "my_light_message" depending
6281 on the current value of 'background'.
6283 You can use multiple brace pairs: >
6284 echo my_{adverb}_{adjective}_message
6285 ..or even nest them: >
6286 echo my_{ad{end_of_word}}_message
6287 where "end_of_word" is either "verb" or "jective".
6289 However, the expression inside the braces must evaluate to a valid single
6290 variable name, e.g. this is invalid: >
6293 .. since the result of expansion is "ca + bd", which is not a variable name.
6295 *curly-braces-function-names*
6296 You can call and define functions by an evaluated name in a similar way.
6298 :let func_end='whizz'
6299 :call my_func_{func_end}(parameter)
6301 This would call the function "my_func_whizz(parameter)".
6303 ==============================================================================
6304 7. Commands *expression-commands*
6306 :let {var-name} = {expr1} *:let* *E18*
6307 Set internal variable {var-name} to the result of the
6308 expression {expr1}. The variable will get the type
6309 from the {expr}. If {var-name} didn't exist yet, it
6312 :let {var-name}[{idx}] = {expr1} *E689*
6313 Set a list item to the result of the expression
6314 {expr1}. {var-name} must refer to a list and {idx}
6315 must be a valid index in that list. For nested list
6316 the index can be repeated.
6317 This cannot be used to add an item to a |List|.
6318 This cannot be used to set a byte in a String. You
6319 can do that like this: >
6320 :let var = var[0:2] . 'X' . var[4:]
6323 :let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710*
6324 Set a sequence of items in a |List| to the result of
6325 the expression {expr1}, which must be a list with the
6326 correct number of items.
6327 {idx1} can be omitted, zero is used instead.
6328 {idx2} can be omitted, meaning the end of the list.
6329 When the selected range of items is partly past the
6330 end of the list, items will be added.
6332 *:let+=* *:let-=* *:let.=* *E734*
6333 :let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
6334 :let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
6335 :let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
6336 These fail if {var} was not set yet and when the type
6337 of {var} and {expr1} don't fit the operator.
6340 :let ${env-name} = {expr1} *:let-environment* *:let-$*
6341 Set environment variable {env-name} to the result of
6342 the expression {expr1}. The type is always String.
6343 :let ${env-name} .= {expr1}
6344 Append {expr1} to the environment variable {env-name}.
6345 If the environment variable didn't exist yet this
6348 :let @{reg-name} = {expr1} *:let-register* *:let-@*
6349 Write the result of the expression {expr1} in register
6350 {reg-name}. {reg-name} must be a single letter, and
6351 must be the name of a writable register (see
6352 |registers|). "@@" can be used for the unnamed
6353 register, "@/" for the search pattern.
6354 If the result of {expr1} ends in a <CR> or <NL>, the
6355 register will be linewise, otherwise it will be set to
6357 This can be used to clear the last search pattern: >
6359 < This is different from searching for an empty string,
6360 that would match everywhere.
6362 :let @{reg-name} .= {expr1}
6363 Append {expr1} to register {reg-name}. If the
6364 register was empty it's like setting it to {expr1}.
6366 :let &{option-name} = {expr1} *:let-option* *:let-&*
6367 Set option {option-name} to the result of the
6368 expression {expr1}. A String or Number value is
6369 always converted to the type of the option.
6370 For an option local to a window or buffer the effect
6371 is just like using the |:set| command: both the local
6372 value and the global value are changed.
6374 :let &path = &path . ',/usr/local/include'
6376 :let &{option-name} .= {expr1}
6377 For a string option: Append {expr1} to the value.
6378 Does not insert a comma like |:set+=|.
6380 :let &{option-name} += {expr1}
6381 :let &{option-name} -= {expr1}
6382 For a number or boolean option: Add or subtract
6385 :let &l:{option-name} = {expr1}
6386 :let &l:{option-name} .= {expr1}
6387 :let &l:{option-name} += {expr1}
6388 :let &l:{option-name} -= {expr1}
6389 Like above, but only set the local value of an option
6390 (if there is one). Works like |:setlocal|.
6392 :let &g:{option-name} = {expr1}
6393 :let &g:{option-name} .= {expr1}
6394 :let &g:{option-name} += {expr1}
6395 :let &g:{option-name} -= {expr1}
6396 Like above, but only set the global value of an option
6397 (if there is one). Works like |:setglobal|.
6399 :let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
6400 {expr1} must evaluate to a |List|. The first item in
6401 the list is assigned to {name1}, the second item to
6403 The number of names must match the number of items in
6405 Each name can be one of the items of the ":let"
6406 command as mentioned above.
6408 :let [s, item] = GetItem(s)
6409 < Detail: {expr1} is evaluated first, then the
6410 assignments are done in sequence. This matters if
6411 {name2} depends on {name1}. Example: >
6414 :let [i, x[i]] = [1, 2]
6416 < The result is [0, 2].
6418 :let [{name1}, {name2}, ...] .= {expr1}
6419 :let [{name1}, {name2}, ...] += {expr1}
6420 :let [{name1}, {name2}, ...] -= {expr1}
6421 Like above, but append/add/subtract the value for each
6424 :let [{name}, ..., ; {lastname}] = {expr1}
6425 Like |:let-unpack| above, but the |List| may have more
6426 items than there are names. A list of the remaining
6427 items is assigned to {lastname}. If there are no
6428 remaining items {lastname} is set to an empty list.
6430 :let [a, b; rest] = ["aval", "bval", 3, 4]
6432 :let [{name}, ..., ; {lastname}] .= {expr1}
6433 :let [{name}, ..., ; {lastname}] += {expr1}
6434 :let [{name}, ..., ; {lastname}] -= {expr1}
6435 Like above, but append/add/subtract the value for each
6438 :let {var-name} .. List the value of variable {var-name}. Multiple
6439 variable names may be given. Special names recognized
6442 b: local buffer variables
6443 w: local window variables
6444 t: local tab page variables
6445 s: script-local variables
6446 l: local function variables
6449 :let List the values of all variables. The type of the
6450 variable is indicated before the value:
6456 :unl[et][!] {name} ... *:unlet* *:unl* *E108* *E795*
6457 Remove the internal variable {name}. Several variable
6458 names can be given, they are all removed. The name
6459 may also be a |List| or |Dictionary| item.
6460 With [!] no error message is given for non-existing
6462 One or more items from a |List| can be removed: >
6463 :unlet list[3] " remove fourth item
6464 :unlet list[3:] " remove fourth item to last
6465 < One item from a |Dictionary| can be removed at a time: >
6468 < This is especially useful to clean up used global
6469 variables and script-local variables (these are not
6470 deleted when the script ends). Function-local
6471 variables are automatically deleted when the function
6474 :lockv[ar][!] [depth] {name} ... *:lockvar* *:lockv*
6475 Lock the internal variable {name}. Locking means that
6476 it can no longer be changed (until it is unlocked).
6477 A locked variable can be deleted: >
6479 :let v = 'asdf' " fails!
6482 If you try to change a locked variable you get an
6483 error message: "E741: Value of {name} is locked"
6485 [depth] is relevant when locking a |List| or
6486 |Dictionary|. It specifies how deep the locking goes:
6487 1 Lock the |List| or |Dictionary| itself,
6488 cannot add or remove items, but can
6489 still change their values.
6490 2 Also lock the values, cannot change
6491 the items. If an item is a |List| or
6492 |Dictionary|, cannot add or remove
6493 items, but can still change the
6495 3 Like 2 but for the |List| /
6496 |Dictionary| in the |List| /
6497 |Dictionary|, one level deeper.
6498 The default [depth] is 2, thus when {name} is a |List|
6499 or |Dictionary| the values cannot be changed.
6501 For unlimited depth use [!] and omit [depth].
6502 However, there is a maximum depth of 100 to catch
6505 Note that when two variables refer to the same |List|
6506 and you lock one of them, the |List| will also be
6507 locked when used through the other variable.
6509 :let l = [0, 1, 2, 3]
6512 :let cl[1] = 99 " won't work!
6513 < You may want to make a copy of a list to avoid this.
6517 :unlo[ckvar][!] [depth] {name} ... *:unlockvar* *:unlo*
6518 Unlock the internal variable {name}. Does the
6519 opposite of |:lockvar|.
6522 :if {expr1} *:if* *:endif* *:en* *E171* *E579* *E580*
6523 :en[dif] Execute the commands until the next matching ":else"
6524 or ":endif" if {expr1} evaluates to non-zero.
6526 From Vim version 4.5 until 5.0, every Ex command in
6527 between the ":if" and ":endif" is ignored. These two
6528 commands were just to allow for future expansions in a
6529 backwards compatible way. Nesting was allowed. Note
6530 that any ":else" or ":elseif" was ignored, the "else"
6531 part was not executed either.
6533 You can use this to remain compatible with older
6536 : version-5-specific-commands
6538 < The commands still need to be parsed to find the
6539 "endif". Sometimes an older Vim has a problem with a
6540 new command. For example, ":silent" is recognized as
6541 a ":substitute" command. In that case ":execute" can
6544 : execute "silent 1,$delete"
6547 NOTE: The ":append" and ":insert" commands don't work
6548 properly in between ":if" and ":endif".
6550 *:else* *:el* *E581* *E583*
6551 :el[se] Execute the commands until the next matching ":else"
6552 or ":endif" if they previously were not being
6555 *:elseif* *:elsei* *E582* *E584*
6556 :elsei[f] {expr1} Short for ":else" ":if", with the addition that there
6557 is no extra ":endif".
6559 :wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw*
6560 *E170* *E585* *E588* *E733*
6561 :endw[hile] Repeat the commands between ":while" and ":endwhile",
6562 as long as {expr1} evaluates to non-zero.
6563 When an error is detected from a command inside the
6564 loop, execution continues after the "endwhile".
6567 :while lnum <= line("$")
6569 :let lnum = lnum + 1
6572 NOTE: The ":append" and ":insert" commands don't work
6573 properly inside a ":while" and ":for" loop.
6575 :for {var} in {list} *:for* *E690* *E732*
6576 :endfo[r] *:endfo* *:endfor*
6577 Repeat the commands between ":for" and ":endfor" for
6578 each item in {list}. Variable {var} is set to the
6580 When an error is detected for a command inside the
6581 loop, execution continues after the "endfor".
6582 Changing {list} inside the loop affects what items are
6583 used. Make a copy if this is unwanted: >
6584 :for item in copy(mylist)
6585 < When not making a copy, Vim stores a reference to the
6586 next item in the list, before executing the commands
6587 with the current item. Thus the current item can be
6588 removed without effect. Removing any later item means
6589 it will not be found. Thus the following example
6590 works (an inefficient way to make a list empty): >
6592 :call remove(mylist, 0)
6594 < Note that reordering the list (e.g., with sort() or
6595 reverse()) may have unexpected effects.
6596 Note that the type of each list item should be
6597 identical to avoid errors for the type of {var}
6598 changing. Unlet the variable at the end of the loop
6599 to allow multiple item types.
6601 :for [{var1}, {var2}, ...] in {listlist}
6603 Like ":for" above, but each item in {listlist} must be
6604 a list, of which each item is assigned to {var1},
6605 {var2}, etc. Example: >
6606 :for [lnum, col] in [[1, 3], [2, 5], [3, 8]]
6607 :echo getline(lnum)[col]
6610 *:continue* *:con* *E586*
6611 :con[tinue] When used inside a ":while" or ":for" loop, jumps back
6612 to the start of the loop.
6613 If it is used after a |:try| inside the loop but
6614 before the matching |:finally| (if present), the
6615 commands following the ":finally" up to the matching
6616 |:endtry| are executed first. This process applies to
6617 all nested ":try"s inside the loop. The outermost
6618 ":endtry" then jumps back to the start of the loop.
6620 *:break* *:brea* *E587*
6621 :brea[k] When used inside a ":while" or ":for" loop, skips to
6622 the command after the matching ":endwhile" or
6624 If it is used after a |:try| inside the loop but
6625 before the matching |:finally| (if present), the
6626 commands following the ":finally" up to the matching
6627 |:endtry| are executed first. This process applies to
6628 all nested ":try"s inside the loop. The outermost
6629 ":endtry" then jumps to the command after the loop.
6631 :try *:try* *:endt* *:endtry* *E600* *E601* *E602*
6632 :endt[ry] Change the error handling for the commands between
6633 ":try" and ":endtry" including everything being
6634 executed across ":source" commands, function calls,
6635 or autocommand invocations.
6637 When an error or interrupt is detected and there is
6638 a |:finally| command following, execution continues
6639 after the ":finally". Otherwise, or when the
6640 ":endtry" is reached thereafter, the next
6641 (dynamically) surrounding ":try" is checked for
6642 a corresponding ":finally" etc. Then the script
6643 processing is terminated. (Whether a function
6644 definition has an "abort" argument does not matter.)
6646 :try | edit too much | finally | echo "cleanup" | endtry
6647 :echo "impossible" " not reached, script terminated above
6649 Moreover, an error or interrupt (dynamically) inside
6650 ":try" and ":endtry" is converted to an exception. It
6651 can be caught as if it were thrown by a |:throw|
6652 command (see |:catch|). In this case, the script
6653 processing is not terminated.
6655 The value "Vim:Interrupt" is used for an interrupt
6656 exception. An error in a Vim command is converted
6657 to a value of the form "Vim({command}):{errmsg}",
6658 other errors are converted to a value of the form
6659 "Vim:{errmsg}". {command} is the full command name,
6660 and {errmsg} is the message that is displayed if the
6661 error exception is not caught, always beginning with
6664 :try | sleep 100 | catch /^Vim:Interrupt$/ | endtry
6665 :try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry
6667 *:cat* *:catch* *E603* *E604* *E605*
6668 :cat[ch] /{pattern}/ The following commands until the next ":catch",
6669 |:finally|, or |:endtry| that belongs to the same
6670 |:try| as the ":catch" are executed when an exception
6671 matching {pattern} is being thrown and has not yet
6672 been caught by a previous ":catch". Otherwise, these
6673 commands are skipped.
6674 When {pattern} is omitted all errors are caught.
6676 :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C)
6677 :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors
6678 :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts
6679 :catch /^Vim(write):/ " catch all errors in :write
6680 :catch /^Vim\%((\a\+)\)\=:E123/ " catch error E123
6681 :catch /my-exception/ " catch user exception
6682 :catch /.*/ " catch everything
6683 :catch " same as /.*/
6685 Another character can be used instead of / around the
6686 {pattern}, so long as it does not have a special
6687 meaning (e.g., '|' or '"') and doesn't occur inside
6689 NOTE: It is not reliable to ":catch" the TEXT of
6690 an error message because it may vary in different
6693 *:fina* *:finally* *E606* *E607*
6694 :fina[lly] The following commands until the matching |:endtry|
6695 are executed whenever the part between the matching
6696 |:try| and the ":finally" is left: either by falling
6697 through to the ":finally" or by a |:continue|,
6698 |:break|, |:finish|, or |:return|, or by an error or
6699 interrupt or exception (see |:throw|).
6701 *:th* *:throw* *E608*
6702 :th[row] {expr1} The {expr1} is evaluated and thrown as an exception.
6703 If the ":throw" is used after a |:try| but before the
6704 first corresponding |:catch|, commands are skipped
6705 until the first ":catch" matching {expr1} is reached.
6706 If there is no such ":catch" or if the ":throw" is
6707 used after a ":catch" but before the |:finally|, the
6708 commands following the ":finally" (if present) up to
6709 the matching |:endtry| are executed. If the ":throw"
6710 is after the ":finally", commands up to the ":endtry"
6711 are skipped. At the ":endtry", this process applies
6712 again for the next dynamically surrounding ":try"
6713 (which may be found in a calling function or sourcing
6714 script), until a matching ":catch" has been found.
6715 If the exception is not caught, the command processing
6718 :try | throw "oops" | catch /^oo/ | echo "caught" | endtry
6722 :ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The
6723 first {expr1} starts on a new line.
6724 Also see |:comment|.
6725 Use "\n" to start a new line. Use "\r" to move the
6726 cursor to the first column.
6727 Uses the highlighting set by the |:echohl| command.
6728 Cannot be followed by a comment.
6730 :echo "the value of 'shell' is" &shell
6732 A later redraw may make the message disappear again.
6733 And since Vim mostly postpones redrawing until it's
6734 finished with a sequence of commands this happens
6735 quite often. To avoid that a command from before the
6736 ":echo" causes a redraw afterwards (redraws are often
6737 postponed until you type something), force a redraw
6738 with the |:redraw| command. Example: >
6739 :new | redraw | echo "there is a new window"
6742 :echon {expr1} .. Echoes each {expr1}, without anything added. Also see
6744 Uses the highlighting set by the |:echohl| command.
6745 Cannot be followed by a comment.
6747 :echon "the value of 'shell' is " &shell
6749 Note the difference between using ":echo", which is a
6750 Vim command, and ":!echo", which is an external shell
6752 :!echo % --> filename
6753 < The arguments of ":!" are expanded, see |:_%|. >
6754 :!echo "%" --> filename or "filename"
6755 < Like the previous example. Whether you see the double
6756 quotes or not depends on your 'shell'. >
6758 < The '%' is an illegal character in an expression. >
6760 < This just echoes the '%' character. >
6761 :echo expand("%") --> filename
6762 < This calls the expand() function to expand the '%'.
6765 :echoh[l] {name} Use the highlight group {name} for the following
6766 |:echo|, |:echon| and |:echomsg| commands. Also used
6767 for the |input()| prompt. Example: >
6768 :echohl WarningMsg | echo "Don't panic!" | echohl None
6769 < Don't forget to set the group back to "None",
6770 otherwise all following echo's will be highlighted.
6773 :echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the
6774 message in the |message-history|.
6775 Spaces are placed between the arguments as with the
6776 |:echo| command. But unprintable characters are
6777 displayed, not interpreted.
6778 The parsing works slightly different from |:echo|,
6779 more like |:execute|. All the expressions are first
6780 evaluated and concatenated before echoing anything.
6781 The expressions must evaluate to a Number or String, a
6782 Dictionary or List causes an error.
6783 Uses the highlighting set by the |:echohl| command.
6785 :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."
6786 < See |:echo-redraw| to avoid the message disappearing
6787 when the screen is redrawn.
6789 :echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the
6790 message in the |message-history|. When used in a
6791 script or function the line number will be added.
6792 Spaces are placed between the arguments as with the
6793 :echo command. When used inside a try conditional,
6794 the message is raised as an error exception instead
6795 (see |try-echoerr|).
6797 :echoerr "This script just failed!"
6798 < If you just want a highlighted message use |:echohl|.
6799 And to get a beep: >
6800 :exe "normal \<Esc>"
6803 :exe[cute] {expr1} .. Executes the string that results from the evaluation
6804 of {expr1} as an Ex command. Multiple arguments are
6805 concatenated, with a space in between. {expr1} is
6806 used as the processed command, command line editing
6807 keys are not recognized.
6808 Cannot be followed by a comment.
6810 :execute "buffer " nextbuf
6811 :execute "normal " count . "w"
6813 ":execute" can be used to append a command to commands
6814 that don't accept a '|'. Example: >
6815 :execute '!ls' | echo "theend"
6817 < ":execute" is also a nice way to avoid having to type
6818 control characters in a Vim script for a ":normal"
6820 :execute "normal ixxx\<Esc>"
6821 < This has an <Esc> character, see |expr-string|.
6823 Be careful to correctly escape special characters in
6824 file names. The |fnameescape()| function can be used
6825 for Vim commands, |shellescape()| for |:!| commands.
6827 :execute "e " . fnameescape(filename)
6828 :execute "!ls " . shellescape(expand('%:h'), 1)
6830 Note: The executed string may be any command-line, but
6831 you cannot start or end a "while", "for" or "if"
6832 command. Thus this is illegal: >
6833 :execute 'while i > 5'
6834 :execute 'echo "test" | break'
6836 It is allowed to have a "while" or "if" command
6837 completely in the executed string: >
6838 :execute 'while i < 5 | echo i | let i = i + 1 | endwhile'
6842 ":execute", ":echo" and ":echon" cannot be followed by
6843 a comment directly, because they see the '"' as the
6844 start of a string. But, you can use '|' followed by a
6846 :echo "foo" | "this is a comment
6848 ==============================================================================
6849 8. Exception handling *exception-handling*
6851 The Vim script language comprises an exception handling feature. This section
6852 explains how it can be used in a Vim script.
6854 Exceptions may be raised by Vim on an error or on interrupt, see
6855 |catch-errors| and |catch-interrupt|. You can also explicitly throw an
6856 exception by using the ":throw" command, see |throw-catch|.
6859 TRY CONDITIONALS *try-conditionals*
6861 Exceptions can be caught or can cause cleanup code to be executed. You can
6862 use a try conditional to specify catch clauses (that catch exceptions) and/or
6863 a finally clause (to be executed for cleanup).
6864 A try conditional begins with a |:try| command and ends at the matching
6865 |:endtry| command. In between, you can use a |:catch| command to start
6866 a catch clause, or a |:finally| command to start a finally clause. There may
6867 be none or multiple catch clauses, but there is at most one finally clause,
6868 which must not be followed by any catch clauses. The lines before the catch
6869 clauses and the finally clause is called a try block. >
6885 : ... FINALLY CLAUSE
6889 The try conditional allows to watch code for exceptions and to take the
6890 appropriate actions. Exceptions from the try block may be caught. Exceptions
6891 from the try block and also the catch clauses may cause cleanup actions.
6892 When no exception is thrown during execution of the try block, the control
6893 is transferred to the finally clause, if present. After its execution, the
6894 script continues with the line following the ":endtry".
6895 When an exception occurs during execution of the try block, the remaining
6896 lines in the try block are skipped. The exception is matched against the
6897 patterns specified as arguments to the ":catch" commands. The catch clause
6898 after the first matching ":catch" is taken, other catch clauses are not
6899 executed. The catch clause ends when the next ":catch", ":finally", or
6900 ":endtry" command is reached - whatever is first. Then, the finally clause
6901 (if present) is executed. When the ":endtry" is reached, the script execution
6902 continues in the following line as usual.
6903 When an exception that does not match any of the patterns specified by the
6904 ":catch" commands is thrown in the try block, the exception is not caught by
6905 that try conditional and none of the catch clauses is executed. Only the
6906 finally clause, if present, is taken. The exception pends during execution of
6907 the finally clause. It is resumed at the ":endtry", so that commands after
6908 the ":endtry" are not executed and the exception might be caught elsewhere,
6910 When during execution of a catch clause another exception is thrown, the
6911 remaining lines in that catch clause are not executed. The new exception is
6912 not matched against the patterns in any of the ":catch" commands of the same
6913 try conditional and none of its catch clauses is taken. If there is, however,
6914 a finally clause, it is executed, and the exception pends during its
6915 execution. The commands following the ":endtry" are not executed. The new
6916 exception might, however, be caught elsewhere, see |try-nesting|.
6917 When during execution of the finally clause (if present) an exception is
6918 thrown, the remaining lines in the finally clause are skipped. If the finally
6919 clause has been taken because of an exception from the try block or one of the
6920 catch clauses, the original (pending) exception is discarded. The commands
6921 following the ":endtry" are not executed, and the exception from the finally
6922 clause is propagated and can be caught elsewhere, see |try-nesting|.
6924 The finally clause is also executed, when a ":break" or ":continue" for
6925 a ":while" loop enclosing the complete try conditional is executed from the
6926 try block or a catch clause. Or when a ":return" or ":finish" is executed
6927 from the try block or a catch clause of a try conditional in a function or
6928 sourced script, respectively. The ":break", ":continue", ":return", or
6929 ":finish" pends during execution of the finally clause and is resumed when the
6930 ":endtry" is reached. It is, however, discarded when an exception is thrown
6931 from the finally clause.
6932 When a ":break" or ":continue" for a ":while" loop enclosing the complete
6933 try conditional or when a ":return" or ":finish" is encountered in the finally
6934 clause, the rest of the finally clause is skipped, and the ":break",
6935 ":continue", ":return" or ":finish" is executed as usual. If the finally
6936 clause has been taken because of an exception or an earlier ":break",
6937 ":continue", ":return", or ":finish" from the try block or a catch clause,
6938 this pending exception or command is discarded.
6940 For examples see |throw-catch| and |try-finally|.
6943 NESTING OF TRY CONDITIONALS *try-nesting*
6945 Try conditionals can be nested arbitrarily. That is, a complete try
6946 conditional can be put into the try block, a catch clause, or the finally
6947 clause of another try conditional. If the inner try conditional does not
6948 catch an exception thrown in its try block or throws a new exception from one
6949 of its catch clauses or its finally clause, the outer try conditional is
6950 checked according to the rules above. If the inner try conditional is in the
6951 try block of the outer try conditional, its catch clauses are checked, but
6952 otherwise only the finally clause is executed. It does not matter for
6953 nesting, whether the inner try conditional is directly contained in the outer
6954 one, or whether the outer one sources a script or calls a function containing
6955 the inner try conditional.
6957 When none of the active try conditionals catches an exception, just their
6958 finally clauses are executed. Thereafter, the script processing terminates.
6959 An error message is displayed in case of an uncaught exception explicitly
6960 thrown by a ":throw" command. For uncaught error and interrupt exceptions
6961 implicitly raised by Vim, the error message(s) or interrupt message are shown
6964 For examples see |throw-catch|.
6967 EXAMINING EXCEPTION HANDLING CODE *except-examine*
6969 Exception handling code can get tricky. If you are in doubt what happens, set
6970 'verbose' to 13 or use the ":13verbose" command modifier when sourcing your
6971 script file. Then you see when an exception is thrown, discarded, caught, or
6972 finished. When using a verbosity level of at least 14, things pending in
6973 a finally clause are also shown. This information is also given in debug mode
6974 (see |debug-scripts|).
6977 THROWING AND CATCHING EXCEPTIONS *throw-catch*
6979 You can throw any number or string as an exception. Use the |:throw| command
6980 and pass the value to be thrown as argument: >
6983 < *throw-expression*
6984 You can also specify an expression argument. The expression is then evaluated
6985 first, and the result is thrown: >
6986 :throw 4705 + strlen("string")
6987 :throw strpart("strings", 0, 6)
6989 An exception might be thrown during evaluation of the argument of the ":throw"
6990 command. Unless it is caught there, the expression evaluation is abandoned.
6991 The ":throw" command then does not throw a new exception.
7007 :throw Foo("arrgh") + Bar()
7009 This throws "arrgh", and "in Bar" is not displayed since Bar() is not
7011 :throw Foo("foo") + Bar()
7012 however displays "in Bar" and throws 4711.
7014 Any other command that takes an expression as argument might also be
7015 abandoned by an (uncaught) exception during the expression evaluation. The
7016 exception is then propagated to the caller of the command.
7025 Here neither of "then" or "else" is displayed.
7028 Exceptions can be caught by a try conditional with one or more |:catch|
7029 commands, see |try-conditionals|. The values to be caught by each ":catch"
7030 command can be specified as a pattern argument. The subsequent catch clause
7031 gets executed when a matching exception is caught.
7034 :function! Foo(value)
7038 : echo "Number thrown"
7040 : echo "String thrown"
7047 The first call to Foo() displays "Number thrown", the second "String thrown".
7048 An exception is matched against the ":catch" commands in the order they are
7049 specified. Only the first match counts. So you should place the more
7050 specific ":catch" first. The following order does not make sense: >
7053 : echo "String thrown"
7055 : echo "Number thrown"
7057 The first ":catch" here matches always, so that the second catch clause is
7061 If you catch an exception by a general pattern, you may access the exact value
7062 in the variable |v:exception|: >
7065 : echo "Number thrown. Value is" v:exception
7067 You may also be interested where an exception was thrown. This is stored in
7068 |v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the
7069 exception most recently caught as long it is not finished.
7073 : if v:exception != ""
7074 : echo 'Caught "' . v:exception . '" in ' . v:throwpoint
7076 : echo 'Nothing caught'
7104 Caught "4711" in function Foo, line 4
7105 Caught "oops" in function Foo, line 10
7108 A practical example: The following command ":LineNumber" displays the line
7109 number in the script or function where it has been used: >
7111 :function! LineNumber()
7112 : return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")
7114 :command! LineNumber try | throw "" | catch | echo LineNumber() | endtry
7117 An exception that is not caught by a try conditional can be caught by
7118 a surrounding try conditional: >
7126 : echo "inner finally"
7132 The inner try conditional does not catch the exception, just its finally
7133 clause is executed. The exception is then caught by the outer try
7134 conditional. The example displays "inner finally" and then "foo".
7137 You can catch an exception and throw a new one to be caught elsewhere from the
7148 : echo "Caught foo, throw bar"
7156 : echo "Caught" v:exception
7159 This displays "Caught foo, throw bar" and then "Caught bar".
7162 There is no real rethrow in the Vim script language, but you may throw
7163 "v:exception" instead: >
7169 : echo "Rethrow" v:exception
7174 Note that this method cannot be used to "rethrow" Vim error or interrupt
7175 exceptions, because it is not possible to fake Vim internal exceptions.
7176 Trying so causes an error exception. You should throw your own exception
7177 denoting the situation. If you want to cause a Vim error exception containing
7178 the original error exception value, you can use the |:echoerr| command: >
7184 : echoerr v:exception
7192 Vim(echoerr):Vim:E492: Not an editor command: asdf ~
7195 CLEANUP CODE *try-finally*
7197 Scripts often change global settings and restore them at their end. If the
7198 user however interrupts the script by pressing CTRL-C, the settings remain in
7199 an inconsistent state. The same may happen to you in the development phase of
7200 a script when an error occurs or you explicitly throw an exception without
7201 catching it. You can solve these problems by using a try conditional with
7202 a finally clause for restoring the settings. Its execution is guaranteed on
7203 normal control flow, on error, on an explicit ":throw", and on interrupt.
7204 (Note that errors and interrupts from inside the try conditional are converted
7205 to exceptions. When not caught, they terminate the script after the finally
7206 clause has been executed.)
7210 : let s:saved_ts = &ts
7213 : " Do the hard work here.
7216 : let &ts = s:saved_ts
7220 This method should be used locally whenever a function or part of a script
7221 changes global settings which need to be restored on failure or normal exit of
7222 that function or script part.
7225 Cleanup code works also when the try block or a catch clause is left by
7226 a ":continue", ":break", ":return", or ":finish".
7245 : echo "still in while"
7249 This displays "first", "cleanup", "second", "cleanup", and "end". >
7257 : echo "Foo still active"
7260 :echo Foo() "returned by Foo"
7262 This displays "cleanup" and "4711 returned by Foo". You don't need to add an
7263 extra ":return" in the finally clause. (Above all, this would override the
7266 *except-from-finally*
7267 Using either of ":continue", ":break", ":return", ":finish", or ":throw" in
7268 a finally clause is possible, but not recommended since it abandons the
7269 cleanup actions for the try conditional. But, of course, interrupt and error
7270 exceptions might get raised from a finally clause.
7271 Example where an error in the finally clause stops an interrupt from
7272 working correctly: >
7276 : echo "Press CTRL-C for interrupt"
7284 :echo "Script still running"
7287 If you need to put commands that could fail into a finally clause, you should
7288 think about catching or ignoring the errors in these commands, see
7289 |catch-errors| and |ignore-errors|.
7292 CATCHING ERRORS *catch-errors*
7294 If you want to catch specific errors, you just have to put the code to be
7295 watched in a try block and add a catch clause for the error message. The
7296 presence of the try conditional causes all errors to be converted to an
7297 exception. No message is displayed and |v:errmsg| is not set then. To find
7298 the right pattern for the ":catch" command, you have to know how the format of
7299 the error exception is.
7300 Error exceptions have the following format: >
7302 Vim({cmdname}):{errmsg}
7306 {cmdname} is the name of the command that failed; the second form is used when
7307 the command name is not known. {errmsg} is the error message usually produced
7308 when the error occurs outside try conditionals. It always begins with
7309 a capital "E", followed by a two or three-digit error number, a colon, and
7316 normally produces the error message >
7317 E108: No such variable: "novar"
7318 which is converted inside try conditionals to an exception >
7319 Vim(unlet):E108: No such variable: "novar"
7323 normally produces the error message >
7324 E492: Not an editor command: dwim
7325 which is converted inside try conditionals to an exception >
7326 Vim:E492: Not an editor command: dwim
7328 You can catch all ":unlet" errors by a >
7329 :catch /^Vim(unlet):/
7330 or all errors for misspelled command names by a >
7333 Some error messages may be produced by different commands: >
7337 both produce the error message >
7338 E128: Function name must start with a capital: nofunc
7339 which is converted inside try conditionals to an exception >
7340 Vim(function):E128: Function name must start with a capital: nofunc
7342 Vim(delfunction):E128: Function name must start with a capital: nofunc
7343 respectively. You can catch the error by its number independently on the
7344 command that caused it if you use the following pattern: >
7345 :catch /^Vim(\a\+):E128:/
7347 Some commands like >
7349 produce multiple error messages, here: >
7350 E121: Undefined variable: novar
7351 E15: Invalid expression: novar
7352 Only the first is used for the exception value, since it is the most specific
7353 one (see |except-several-errors|). So you can catch it by >
7354 :catch /^Vim(\a\+):E121:/
7356 You can catch all errors related to the name "nofunc" by >
7359 You can catch all Vim errors in the ":write" and ":read" commands by >
7360 :catch /^Vim(\(write\|read\)):E\d\+:/
7362 You can catch all Vim errors by the pattern >
7363 :catch /^Vim\((\a\+)\)\=:E\d\+:/
7366 NOTE: You should never catch the error message text itself: >
7367 :catch /No such variable/
7368 only works in the english locale, but not when the user has selected
7369 a different language by the |:language| command. It is however helpful to
7370 cite the message text in a comment: >
7371 :catch /^Vim(\a\+):E108:/ " No such variable
7374 IGNORING ERRORS *ignore-errors*
7376 You can ignore errors in a specific Vim command by catching them locally: >
7383 But you are strongly recommended NOT to use this simple form, since it could
7384 catch more than you want. With the ":write" command, some autocommands could
7385 be executed and cause errors not related to writing, for instance: >
7387 :au BufWritePre * unlet novar
7389 There could even be such errors you are not responsible for as a script
7390 writer: a user of your script might have defined such autocommands. You would
7391 then hide the error from the user.
7392 It is much better to use >
7396 :catch /^Vim(write):/
7399 which only catches real write errors. So catch only what you'd like to ignore
7402 For a single command that does not cause execution of autocommands, you could
7403 even suppress the conversion of errors to exceptions by the ":silent!"
7406 This works also when a try conditional is active.
7409 CATCHING INTERRUPTS *catch-interrupt*
7411 When there are active try conditionals, an interrupt (CTRL-C) is converted to
7412 the exception "Vim:Interrupt". You can catch it like every exception. The
7413 script is not terminated, then.
7425 : let command = input("Type a command: ")
7429 : elseif command == "END"
7431 : elseif command == "TASK1"
7433 : elseif command == "TASK2"
7436 : echo "\nIllegal command:" command
7439 : catch /^Vim:Interrupt$/
7440 : echo "\nCommand interrupted"
7441 : " Caught the interrupt. Continue with next prompt.
7445 You can interrupt a task here by pressing CTRL-C; the script then asks for
7446 a new command. If you press CTRL-C at the prompt, the script is terminated.
7448 For testing what happens when CTRL-C would be pressed on a specific line in
7449 your script, use the debug mode and execute the |>quit| or |>interrupt|
7450 command on that line. See |debug-scripts|.
7453 CATCHING ALL *catch-all*
7461 catch everything, error exceptions, interrupt exceptions and exceptions
7462 explicitly thrown by the |:throw| command. This is useful at the top level of
7463 a script in order to catch unexpected things.
7468 : " do the hard work here
7470 :catch /MyException/
7472 : " handle known problem
7474 :catch /^Vim:Interrupt$/
7475 : echo "Script interrupted"
7477 : echo "Internal error (" . v:exception . ")"
7478 : echo " - occurred at " . v:throwpoint
7482 Note: Catching all might catch more things than you want. Thus, you are
7483 strongly encouraged to catch only for problems that you can really handle by
7484 specifying a pattern argument to the ":catch".
7485 Example: Catching all could make it nearly impossible to interrupt a script
7486 by pressing CTRL-C: >
7496 EXCEPTIONS AND AUTOCOMMANDS *except-autocmd*
7498 Exceptions may be used during execution of autocommands. Example: >
7501 :autocmd User x throw "Oops!"
7502 :autocmd User x catch
7503 :autocmd User x echo v:exception
7504 :autocmd User x endtry
7505 :autocmd User x throw "Arrgh!"
7506 :autocmd User x echo "Should not be displayed"
7514 This displays "Oops!" and "Arrgh!".
7516 *except-autocmd-Pre*
7517 For some commands, autocommands get executed before the main action of the
7518 command takes place. If an exception is thrown and not caught in the sequence
7519 of autocommands, the sequence and the command that caused its execution are
7520 abandoned and the exception is propagated to the caller of the command.
7523 :autocmd BufWritePre * throw "FAIL"
7524 :autocmd BufWritePre * echo "Should not be displayed"
7529 : echo "Caught:" v:exception "from" v:throwpoint
7532 Here, the ":write" command does not write the file currently being edited (as
7533 you can see by checking 'modified'), since the exception from the BufWritePre
7534 autocommand abandons the ":write". The exception is then caught and the
7537 Caught: FAIL from BufWrite Auto commands for "*"
7539 *except-autocmd-Post*
7540 For some commands, autocommands get executed after the main action of the
7541 command has taken place. If this main action fails and the command is inside
7542 an active try conditional, the autocommands are skipped and an error exception
7543 is thrown that can be caught by the caller of the command.
7546 :autocmd BufWritePost * echo "File successfully written!"
7549 : write /i/m/p/o/s/s/i/b/l/e
7554 This just displays: >
7556 Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)
7558 If you really need to execute the autocommands even when the main action
7559 fails, trigger the event from the catch clause.
7562 :autocmd BufWritePre * set noreadonly
7563 :autocmd BufWritePost * set readonly
7566 : write /i/m/p/o/s/s/i/b/l/e
7568 : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e
7571 You can also use ":silent!": >
7575 :autocmd BufWritePost * if v:errmsg != ""
7576 :autocmd BufWritePost * let x = "after fail"
7577 :autocmd BufWritePost * endif
7579 : silent! write /i/m/p/o/s/s/i/b/l/e
7584 This displays "after fail".
7586 If the main action of the command does not fail, exceptions from the
7587 autocommands will be catchable by the caller of the command: >
7589 :autocmd BufWritePost * throw ":-("
7590 :autocmd BufWritePost * echo "Should not be displayed"
7598 *except-autocmd-Cmd*
7599 For some commands, the normal action can be replaced by a sequence of
7600 autocommands. Exceptions from that sequence will be catchable by the caller
7602 Example: For the ":write" command, the caller cannot know whether the file
7603 had actually been written when the exception occurred. You need to tell it in
7609 : autocmd BufWriteCmd * if &modified
7610 : autocmd BufWriteCmd * let cnt = cnt + 1
7611 : autocmd BufWriteCmd * if cnt % 3 == 2
7612 : autocmd BufWriteCmd * throw "BufWriteCmdError"
7613 : autocmd BufWriteCmd * endif
7614 : autocmd BufWriteCmd * write | set nomodified
7615 : autocmd BufWriteCmd * if cnt % 3 == 0
7616 : autocmd BufWriteCmd * throw "BufWriteCmdError"
7617 : autocmd BufWriteCmd * endif
7618 : autocmd BufWriteCmd * echo "File successfully written!"
7619 : autocmd BufWriteCmd * endif
7624 :catch /^BufWriteCmdError$/
7626 : echo "Error on writing (file contents not changed)"
7628 : echo "Error after writing"
7630 :catch /^Vim(write):/
7631 : echo "Error on writing"
7634 When this script is sourced several times after making changes, it displays
7636 File successfully written!
7638 Error on writing (file contents not changed)
7643 *except-autocmd-ill*
7644 You cannot spread a try conditional over autocommands for different events.
7645 The following code is ill-formed: >
7647 :autocmd BufWritePre * try
7649 :autocmd BufWritePost * catch
7650 :autocmd BufWritePost * echo v:exception
7651 :autocmd BufWritePost * endtry
7656 EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS *except-hier-param*
7658 Some programming languages allow to use hierarchies of exception classes or to
7659 pass additional information with the object of an exception class. You can do
7660 similar things in Vim.
7661 In order to throw an exception from a hierarchy, just throw the complete
7662 class name with the components separated by a colon, for instance throw the
7663 string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library.
7664 When you want to pass additional information with your exception class, add
7665 it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)"
7666 for an error when writing "myfile".
7667 With the appropriate patterns in the ":catch" command, you can catch for
7668 base classes or derived classes of your hierarchy. Additional information in
7669 parentheses can be cut out from |v:exception| with the ":substitute" command.
7672 :function! CheckRange(a, func)
7674 : throw "EXCEPT:MATHERR:RANGE(" . a:func . ")"
7678 :function! Add(a, b)
7679 : call CheckRange(a:a, "Add")
7680 : call CheckRange(a:b, "Add")
7683 : throw "EXCEPT:MATHERR:OVERFLOW"
7688 :function! Div(a, b)
7689 : call CheckRange(a:a, "Div")
7690 : call CheckRange(a:b, "Div")
7692 : throw "EXCEPT:MATHERR:ZERODIV"
7697 :function! Write(file)
7699 : execute "write" fnameescape(a:file)
7700 : catch /^Vim(write):/
7701 : throw "EXCEPT:IO(" . getcwd() . ", " . a:file . "):WRITEERR"
7707 : " something with arithmetics and I/O
7709 :catch /^EXCEPT:MATHERR:RANGE/
7710 : let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "")
7711 : echo "Range error in" function
7713 :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV
7717 : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "")
7718 : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "")
7720 : let file = dir . "/" . file
7722 : echo 'I/O error for "' . file . '"'
7725 : echo "Unspecified error"
7729 The exceptions raised by Vim itself (on error or when pressing CTRL-C) use
7730 a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself
7731 exceptions with the "Vim" prefix; they are reserved for Vim.
7732 Vim error exceptions are parameterized with the name of the command that
7733 failed, if known. See |catch-errors|.
7738 The exception handling concept requires that the command sequence causing the
7739 exception is aborted immediately and control is transferred to finally clauses
7740 and/or a catch clause.
7742 In the Vim script language there are cases where scripts and functions
7743 continue after an error: in functions without the "abort" flag or in a command
7744 after ":silent!", control flow goes to the following line, and outside
7745 functions, control flow goes to the line following the outermost ":endwhile"
7746 or ":endif". On the other hand, errors should be catchable as exceptions
7747 (thus, requiring the immediate abortion).
7749 This problem has been solved by converting errors to exceptions and using
7750 immediate abortion (if not suppressed by ":silent!") only when a try
7751 conditional is active. This is no restriction since an (error) exception can
7752 be caught only from an active try conditional. If you want an immediate
7753 termination without catching the error, just use a try conditional without
7754 catch clause. (You can cause cleanup code being executed before termination
7755 by specifying a finally clause.)
7757 When no try conditional is active, the usual abortion and continuation
7758 behavior is used instead of immediate abortion. This ensures compatibility of
7759 scripts written for Vim 6.1 and earlier.
7761 However, when sourcing an existing script that does not use exception handling
7762 commands (or when calling one of its functions) from inside an active try
7763 conditional of a new script, you might change the control flow of the existing
7764 script on error. You get the immediate abortion on error and can catch the
7765 error in the new script. If however the sourced script suppresses error
7766 messages by using the ":silent!" command (checking for errors by testing
7767 |v:errmsg| if appropriate), its execution path is not changed. The error is
7768 not converted to an exception. (See |:silent|.) So the only remaining cause
7769 where this happens is for scripts that don't care about errors and produce
7770 error messages. You probably won't want to use such code from your new
7774 Syntax errors in the exception handling commands are never caught by any of
7775 the ":catch" commands of the try conditional they belong to. Its finally
7776 clauses, however, is executed.
7783 : echo "in catch with syntax error"
7785 : echo "inner catch-all"
7787 : echo "inner finally"
7790 : echo 'outer catch-all caught "' . v:exception . '"'
7792 : echo "outer finally"
7797 outer catch-all caught "Vim(catch):E54: Unmatched \("
7799 The original exception is discarded and an error exception is raised, instead.
7801 *except-single-line*
7802 The ":try", ":catch", ":finally", and ":endtry" commands can be put on
7803 a single line, but then syntax errors may make it difficult to recognize the
7804 "catch" line, thus you better avoid this.
7806 :try | unlet! foo # | catch | endtry
7807 raises an error exception for the trailing characters after the ":unlet!"
7808 argument, but does not see the ":catch" and ":endtry" commands, so that the
7809 error exception is discarded and the "E488: Trailing characters" message gets
7812 *except-several-errors*
7813 When several errors appear in a single command, the first error message is
7814 usually the most specific one and therefor converted to the error exception.
7818 E121: Undefined variable: novar
7819 E15: Invalid expression: novar
7820 The value of the error exception inside try conditionals is: >
7821 Vim(echo):E121: Undefined variable: novar
7822 < *except-syntax-error*
7823 But when a syntax error is detected after a normal error in the same command,
7824 the syntax error is used for the exception being thrown.
7828 E108: No such variable: "novar"
7829 E488: Trailing characters
7830 The value of the error exception inside try conditionals is: >
7831 Vim(unlet):E488: Trailing characters
7832 This is done because the syntax error might change the execution path in a way
7833 not intended by the user. Example: >
7835 try | unlet novar # | catch | echo v:exception | endtry
7837 echo "outer catch:" v:exception
7839 This displays "outer catch: Vim(unlet):E488: Trailing characters", and then
7840 a "E600: Missing :endtry" error message is given, see |except-single-line|.
7842 ==============================================================================
7843 9. Examples *eval-examples*
7845 Printing in Binary ~
7847 :" The function Nr2Bin() returns the Hex string of a number.
7852 : let r = '01'[n % 2] . r
7858 :" The function String2Bin() converts each character in a string to a
7859 :" binary string, separated with dashes.
7860 :func String2Bin(str)
7862 : for ix in range(strlen(a:str))
7863 : let out = out . '-' . Nr2Bin(char2nr(a:str[ix]))
7868 Example of its use: >
7871 :echo String2Bin("32")
7872 result: "110011-110010"
7877 This example sorts lines with a specific compare function. >
7880 : let lines = getline(1, '$')
7881 : call sort(lines, function("Strcmp"))
7882 : call setline(1, lines)
7886 :call setline(1, sort(getline(1, '$'), function("Strcmp")))
7889 scanf() replacement ~
7891 There is no sscanf() function in Vim. If you need to extract parts from a
7892 line, you can use matchstr() and substitute() to do it. This example shows
7893 how to get the file name, line number and column number out of a line like
7894 "foobar.txt, 123, 45". >
7895 :" Set up the match bit
7896 :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)'
7897 :"get the part matching the whole expression
7898 :let l = matchstr(line, mx)
7899 :"get each item out of the match
7900 :let file = substitute(l, mx, '\1', '')
7901 :let lnum = substitute(l, mx, '\2', '')
7902 :let col = substitute(l, mx, '\3', '')
7904 The input is in the variable "line", the results in the variables "file",
7905 "lnum" and "col". (idea from Michael Geddes)
7908 getting the scriptnames in a Dictionary ~
7909 *scriptnames-dictionary*
7910 The |:scriptnames| command can be used to get a list of all script files that
7911 have been sourced. There is no equivalent function or variable for this
7912 (because it's rarely needed). In case you need to manipulate the list this
7914 " Get the output of ":scriptnames" in the scriptnames_output variable.
7915 let scriptnames_output = ''
7916 redir => scriptnames_output
7920 " Split the output into lines and parse each line. Add an entry to the
7921 " "scripts" dictionary.
7923 for line in split(scriptnames_output, "\n")
7924 " Only do non-blank lines.
7926 " Get the first number in the line.
7927 let nr = matchstr(line, '\d\+')
7928 " Get the file name, remove the script number " 123: ".
7929 let name = substitute(line, '.\+:\s*', '', '')
7930 " Add an item to the Dictionary
7931 let scripts[nr] = name
7934 unlet scriptnames_output
7936 ==============================================================================
7937 10. No +eval feature *no-eval-feature*
7939 When the |+eval| feature was disabled at compile time, none of the expression
7940 evaluation commands are available. To prevent this from causing Vim scripts
7941 to generate all kinds of errors, the ":if" and ":endif" commands are still
7942 recognized, though the argument of the ":if" and everything between the ":if"
7943 and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but
7944 only if the commands are at the start of the line. The ":else" command is not
7947 Example of how to avoid executing commands when the |+eval| feature is
7951 : echo "Expression evaluation is compiled in"
7953 : echo "You will _never_ see this message"
7956 ==============================================================================
7957 11. The sandbox *eval-sandbox* *sandbox* *E48*
7959 The 'foldexpr', 'includeexpr', 'indentexpr', 'statusline' and 'foldtext'
7960 options are evaluated in a sandbox. This means that you are protected from
7961 these expressions having nasty side effects. This gives some safety for when
7962 these options are set from a modeline. It is also used when the command from
7963 a tags file is executed and for CTRL-R = in the command line.
7964 The sandbox is also used for the |:sandbox| command.
7966 These items are not allowed in the sandbox:
7967 - changing the buffer text
7968 - defining or changing mapping, autocommands, functions, user commands
7969 - setting certain options (see |option-summary|)
7970 - setting certain v: variables (see |v:var|) *E794*
7971 - executing a shell command
7972 - reading or writing a file
7973 - jumping to another buffer or editing a file
7974 - executing Python, Perl, etc. commands
7975 This is not guaranteed 100% secure, but it should block most attacks.
7978 :san[dbox] {cmd} Execute {cmd} in the sandbox. Useful to evaluate an
7979 option that may have been set from a modeline, e.g.
7983 A few options contain an expression. When this expression is evaluated it may
7984 have to be done in the sandbox to avoid a security risk. But the sandbox is
7985 restrictive, thus this only happens when the option was set from an insecure
7986 location. Insecure in this context are:
7987 - sourcing a .vimrc or .exrc in the current directory
7988 - while executing in the sandbox
7989 - value coming from a modeline
7991 Note that when in the sandbox and saving an option value and restoring it, the
7992 option will still be marked as it was set in the sandbox.
7994 ==============================================================================
7995 12. Textlock *textlock*
7997 In a few situations it is not allowed to change the text in the buffer, jump
7998 to another window and some other things that might confuse or break what Vim
7999 is currently doing. This mostly applies to things that happen when Vim is
8000 actually doing something else. For example, evaluating the 'balloonexpr' may
8001 happen any moment the mouse cursor is resting at some position.
8003 This is not allowed when the textlock is active:
8004 - changing the buffer text
8005 - jumping to another buffer or window
8006 - editing another file
8007 - closing a window or quitting Vim
8011 vim:tw=78:ts=8:ft=help:norl: