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