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