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