| blob | 0603e1f619558073379e0c7ed613fe3b7213d0e5 |
1 *eval.txt* For Vim version 7.2. Last change: 2010 Jan 19
4 VIM REFERENCE MANUAL by Bram Moolenaar
7 Expression evaluation *expression* *expr* *E15* *eval*
9 Using expressions is introduced in chapter 41 of the user manual |usr_41.txt|.
11 Note: Expression evaluation can be disabled at compile time. If this has been
12 done, the features in this document are not available. See |+eval| and
13 |no-eval-feature|.
15 1. Variables |variables|
16 1.1 Variable types
17 1.2 Function references |Funcref|
18 1.3 Lists |Lists|
19 1.4 Dictionaries |Dictionaries|
20 1.5 More about variables |more-variables|
21 2. Expression syntax |expression-syntax|
22 3. Internal variable |internal-variables|
23 4. Builtin Functions |functions|
24 5. Defining functions |user-functions|
25 6. Curly braces names |curly-braces-names|
26 7. Commands |expression-commands|
27 8. Exception handling |exception-handling|
28 9. Examples |eval-examples|
29 10. No +eval feature |no-eval-feature|
30 11. The sandbox |eval-sandbox|
31 12. Textlock |textlock|
33 {Vi does not have any of these commands}
35 ==============================================================================
36 1. Variables *variables*
38 1.1 Variable types ~
39 *E712*
40 There are six types of variables:
42 Number A 32 bit signed number. |expr-number| *Number*
43 Examples: -123 0x10 0177
45 Float A floating point number. |floating-point-format| *Float*
46 {only when compiled with the |+float| feature}
47 Examples: 123.456 1.15e-6 -1.1e3
49 String A NUL terminated string of 8-bit unsigned characters (bytes).
50 |expr-string| Examples: "ab\txx\"--" 'x-z''a,c'
52 Funcref A reference to a function |Funcref|.
53 Example: function("strlen")
55 List An ordered sequence of items |List|.
56 Example: [1, 2, ['a', 'b']]
58 Dictionary An associative, unordered array: Each entry has a key and a
59 value. |Dictionary|
60 Example: {'blue': "#0000ff", 'red': "#ff0000"}
62 The Number and String types are converted automatically, depending on how they
63 are used.
65 Conversion from a Number to a String is by making the ASCII representation of
66 the Number. Examples: >
67 Number 123 --> String "123"
68 Number 0 --> String "0"
69 Number -1 --> String "-1"
71 Conversion from a String to a Number is done by converting the first digits
72 to a number. Hexadecimal "0xf9" and Octal "017" numbers are recognized. If
73 the String doesn't start with digits, the result is zero. Examples: >
74 String "456" --> Number 456
75 String "6bar" --> Number 6
76 String "foo" --> Number 0
77 String "0xf1" --> Number 241
78 String "0100" --> Number 64
79 String "-8" --> Number -8
80 String "+8" --> Number 0
82 To force conversion from String to Number, add zero to it: >
83 :echo "0100" + 0
84 < 64 ~
86 To avoid a leading zero to cause octal conversion, or for using a different
87 base, use |str2nr()|.
89 For boolean operators Numbers are used. Zero is FALSE, non-zero is TRUE.
91 Note that in the command >
92 :if "foo"
93 "foo" is converted to 0, which means FALSE. To test for a non-empty string,
94 use strlen(): >
95 :if strlen("foo")
96 < *E745* *E728* *E703* *E729* *E730* *E731*
97 List, Dictionary and Funcref types are not automatically converted.
99 *E805* *E806* *E808*
100 When mixing Number and Float the Number is converted to Float. Otherwise
101 there is no automatic conversion of Float. You can use str2float() for String
102 to Float, printf() for Float to String and float2nr() for Float to Number.
104 *E706* *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.
1025 Note that "\xff" is stored as the byte 255, which may be invalid in some
1026 encodings. Use "\u00ff" to store character 255 according to the current value
1027 of 'encoding'.
1029 Note that "\000" and "\x00" force the end of the string.
1032 literal-string *literal-string* *E115*
1033 ---------------
1034 'string' string constant *expr-'*
1036 Note that single quotes are used.
1038 This string is taken as it is. No backslashes are removed or have a special
1039 meaning. The only exception is that two quotes stand for one quote.
1041 Single quoted strings are useful for patterns, so that backslashes do not need
1042 to be doubled. These two commands are equivalent: >
1043 if a =~ "\\s*"
1044 if a =~ '\s*'
1047 option *expr-option* *E112* *E113*
1048 ------
1049 &option option value, local value if possible
1050 &g:option global option value
1051 &l:option local option value
1053 Examples: >
1054 echo "tabstop is " . &tabstop
1055 if &insertmode
1057 Any option name can be used here. See |options|. When using the local value
1058 and there is no buffer-local or window-local value, the global value is used
1059 anyway.
1062 register *expr-register* *@r*
1063 --------
1064 @r contents of register 'r'
1066 The result is the contents of the named register, as a single string.
1067 Newlines are inserted where required. To get the contents of the unnamed
1068 register use @" or @@. See |registers| for an explanation of the available
1069 registers.
1071 When using the '=' register you get the expression itself, not what it
1072 evaluates to. Use |eval()| to evaluate it.
1075 nesting *expr-nesting* *E110*
1076 -------
1077 (expr1) nested expression
1080 environment variable *expr-env*
1081 --------------------
1082 $VAR environment variable
1084 The String value of any environment variable. When it is not defined, the
1085 result is an empty string.
1086 *expr-env-expand*
1087 Note that there is a difference between using $VAR directly and using
1088 expand("$VAR"). Using it directly will only expand environment variables that
1089 are known inside the current Vim session. Using expand() will first try using
1090 the environment variables known inside the current Vim session. If that
1091 fails, a shell will be used to expand the variable. This can be slow, but it
1092 does expand all variables that the shell knows about. Example: >
1093 :echo $version
1094 :echo expand("$version")
1095 The first one probably doesn't echo anything, the second echoes the $version
1096 variable (if your shell supports it).
1099 internal variable *expr-variable*
1100 -----------------
1101 variable internal variable
1102 See below |internal-variables|.
1105 function call *expr-function* *E116* *E118* *E119* *E120*
1106 -------------
1107 function(expr1, ...) function call
1108 See below |functions|.
1111 ==============================================================================
1112 3. Internal variable *internal-variables* *E121*
1113 *E461*
1114 An internal variable name can be made up of letters, digits and '_'. But it
1115 cannot start with a digit. It's also possible to use curly braces, see
1116 |curly-braces-names|.
1118 An internal variable is created with the ":let" command |:let|.
1119 An internal variable is explicitly destroyed with the ":unlet" command
1120 |:unlet|.
1121 Using a name that is not an internal variable or refers to a variable that has
1122 been destroyed results in an error.
1124 There are several name spaces for variables. Which one is to be used is
1125 specified by what is prepended:
1127 (nothing) In a function: local to a function; otherwise: global
1128 |buffer-variable| b: Local to the current buffer.
1129 |window-variable| w: Local to the current window.
1130 |tabpage-variable| t: Local to the current tab page.
1131 |global-variable| g: Global.
1132 |local-variable| l: Local to a function.
1133 |script-variable| s: Local to a |:source|'ed Vim script.
1134 |function-argument| a: Function argument (only inside a function).
1135 |vim-variable| v: Global, predefined by Vim.
1137 The scope name by itself can be used as a |Dictionary|. For example, to
1138 delete all script-local variables: >
1139 :for k in keys(s:)
1140 : unlet s:[k]
1141 :endfor
1142 <
1143 *buffer-variable* *b:var*
1144 A variable name that is preceded with "b:" is local to the current buffer.
1145 Thus you can have several "b:foo" variables, one for each buffer.
1146 This kind of variable is deleted when the buffer is wiped out or deleted with
1147 |:bdelete|.
1149 One local buffer variable is predefined:
1150 *b:changedtick-variable* *changetick*
1151 b:changedtick The total number of changes to the current buffer. It is
1152 incremented for each change. An undo command is also a change
1153 in this case. This can be used to perform an action only when
1154 the buffer has changed. Example: >
1155 :if my_changedtick != b:changedtick
1156 : let my_changedtick = b:changedtick
1157 : call My_Update()
1158 :endif
1159 <
1160 *window-variable* *w:var*
1161 A variable name that is preceded with "w:" is local to the current window. It
1162 is deleted when the window is closed.
1164 *tabpage-variable* *t:var*
1165 A variable name that is preceded with "t:" is local to the current tab page,
1166 It is deleted when the tab page is closed. {not available when compiled
1167 without the +windows feature}
1169 *global-variable* *g:var*
1170 Inside functions global variables are accessed with "g:". Omitting this will
1171 access a variable local to a function. But "g:" can also be used in any other
1172 place if you like.
1174 *local-variable* *l:var*
1175 Inside functions local variables are accessed without prepending anything.
1176 But you can also prepend "l:" if you like. However, without prepending "l:"
1177 you may run into reserved variable names. For example "count". By itself it
1178 refers to "v:count". Using "l:count" you can have a local variable with the
1179 same name.
1181 *script-variable* *s:var*
1182 In a Vim script variables starting with "s:" can be used. They cannot be
1183 accessed from outside of the scripts, thus are local to the script.
1185 They can be used in:
1186 - commands executed while the script is sourced
1187 - functions defined in the script
1188 - autocommands defined in the script
1189 - functions and autocommands defined in functions and autocommands which were
1190 defined in the script (recursively)
1191 - user defined commands defined in the script
1192 Thus not in:
1193 - other scripts sourced from this one
1194 - mappings
1195 - menus
1196 - etc.
1198 Script variables can be used to avoid conflicts with global variable names.
1199 Take this example: >
1201 let s:counter = 0
1202 function MyCounter()
1203 let s:counter = s:counter + 1
1204 echo s:counter
1205 endfunction
1206 command Tick call MyCounter()
1208 You can now invoke "Tick" from any script, and the "s:counter" variable in
1209 that script will not be changed, only the "s:counter" in the script where
1210 "Tick" was defined is used.
1212 Another example that does the same: >
1214 let s:counter = 0
1215 command Tick let s:counter = s:counter + 1 | echo s:counter
1217 When calling a function and invoking a user-defined command, the context for
1218 script variables is set to the script where the function or command was
1219 defined.
1221 The script variables are also available when a function is defined inside a
1222 function that is defined in a script. Example: >
1224 let s:counter = 0
1225 function StartCounting(incr)
1226 if a:incr
1227 function MyCounter()
1228 let s:counter = s:counter + 1
1229 endfunction
1230 else
1231 function MyCounter()
1232 let s:counter = s:counter - 1
1233 endfunction
1234 endif
1235 endfunction
1237 This defines the MyCounter() function either for counting up or counting down
1238 when calling StartCounting(). It doesn't matter from where StartCounting() is
1239 called, the s:counter variable will be accessible in MyCounter().
1241 When the same script is sourced again it will use the same script variables.
1242 They will remain valid as long as Vim is running. This can be used to
1243 maintain a counter: >
1245 if !exists("s:counter")
1246 let s:counter = 1
1247 echo "script executed for the first time"
1248 else
1249 let s:counter = s:counter + 1
1250 echo "script executed " . s:counter . " times now"
1251 endif
1253 Note that this means that filetype plugins don't get a different set of script
1254 variables for each buffer. Use local buffer variables instead |b:var|.
1257 Predefined Vim variables: *vim-variable* *v:var*
1259 *v:beval_col* *beval_col-variable*
1260 v:beval_col The number of the column, over which the mouse pointer is.
1261 This is the byte index in the |v:beval_lnum| line.
1262 Only valid while evaluating the 'balloonexpr' option.
1264 *v:beval_bufnr* *beval_bufnr-variable*
1265 v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only
1266 valid while evaluating the 'balloonexpr' option.
1268 *v:beval_lnum* *beval_lnum-variable*
1269 v:beval_lnum The number of the line, over which the mouse pointer is. Only
1270 valid while evaluating the 'balloonexpr' option.
1272 *v:beval_text* *beval_text-variable*
1273 v:beval_text The text under or after the mouse pointer. Usually a word as
1274 it is useful for debugging a C program. 'iskeyword' applies,
1275 but a dot and "->" before the position is included. When on a
1276 ']' the text before it is used, including the matching '[' and
1277 word before it. When on a Visual area within one line the
1278 highlighted text is used.
1279 Only valid while evaluating the 'balloonexpr' option.
1281 *v:beval_winnr* *beval_winnr-variable*
1282 v:beval_winnr The number of the window, over which the mouse pointer is. Only
1283 valid while evaluating the 'balloonexpr' option.
1285 *v:char* *char-variable*
1286 v:char Argument for evaluating 'formatexpr' and used for the typed
1287 character when using <expr> in an abbreviation |map-<expr>|.
1289 *v:charconvert_from* *charconvert_from-variable*
1290 v:charconvert_from
1291 The name of the character encoding of a file to be converted.
1292 Only valid while evaluating the 'charconvert' option.
1294 *v:charconvert_to* *charconvert_to-variable*
1295 v:charconvert_to
1296 The name of the character encoding of a file after conversion.
1297 Only valid while evaluating the 'charconvert' option.
1299 *v:cmdarg* *cmdarg-variable*
1300 v:cmdarg This variable is used for two purposes:
1301 1. The extra arguments given to a file read/write command.
1302 Currently these are "++enc=" and "++ff=". This variable is
1303 set before an autocommand event for a file read/write
1304 command is triggered. There is a leading space to make it
1305 possible to append this variable directly after the
1306 read/write command. Note: The "+cmd" argument isn't
1307 included here, because it will be executed anyway.
1308 2. When printing a PostScript file with ":hardcopy" this is
1309 the argument for the ":hardcopy" command. This can be used
1310 in 'printexpr'.
1312 *v:cmdbang* *cmdbang-variable*
1313 v:cmdbang Set like v:cmdarg for a file read/write command. When a "!"
1314 was used the value is 1, otherwise it is 0. Note that this
1315 can only be used in autocommands. For user commands |<bang>|
1316 can be used.
1318 *v:count* *count-variable*
1319 v:count The count given for the last Normal mode command. Can be used
1320 to get the count before a mapping. Read-only. Example: >
1321 :map _x :<C-U>echo "the count is " . v:count<CR>
1322 < Note: The <C-U> is required to remove the line range that you
1323 get when typing ':' after a count.
1324 When there are two counts, as in "3d2w", they are multiplied,
1325 just like what happens in the command, "d6w" for the example.
1326 Also used for evaluating the 'formatexpr' option.
1327 "count" also works, for backwards compatibility.
1329 *v:count1* *count1-variable*
1330 v:count1 Just like "v:count", but defaults to one when no count is
1331 used.
1333 *v:ctype* *ctype-variable*
1334 v:ctype The current locale setting for characters of the runtime
1335 environment. This allows Vim scripts to be aware of the
1336 current locale encoding. Technical: it's the value of
1337 LC_CTYPE. When not using a locale the value is "C".
1338 This variable can not be set directly, use the |:language|
1339 command.
1340 See |multi-lang|.
1342 *v:dying* *dying-variable*
1343 v:dying Normally zero. When a deadly signal is caught it's set to
1344 one. When multiple signals are caught the number increases.
1345 Can be used in an autocommand to check if Vim didn't
1346 terminate normally. {only works on Unix}
1347 Example: >
1348 :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
1349 <
1350 *v:errmsg* *errmsg-variable*
1351 v:errmsg Last given error message. It's allowed to set this variable.
1352 Example: >
1353 :let v:errmsg = ""
1354 :silent! next
1355 :if v:errmsg != ""
1356 : ... handle error
1357 < "errmsg" also works, for backwards compatibility.
1359 *v:exception* *exception-variable*
1360 v:exception The value of the exception most recently caught and not
1361 finished. See also |v:throwpoint| and |throw-variables|.
1362 Example: >
1363 :try
1364 : throw "oops"
1365 :catch /.*/
1366 : echo "caught" v:exception
1367 :endtry
1368 < Output: "caught oops".
1370 *v:fcs_reason* *fcs_reason-variable*
1371 v:fcs_reason The reason why the |FileChangedShell| event was triggered.
1372 Can be used in an autocommand to decide what to do and/or what
1373 to set v:fcs_choice to. Possible values:
1374 deleted file no longer exists
1375 conflict file contents, mode or timestamp was
1376 changed and buffer is modified
1377 changed file contents has changed
1378 mode mode of file changed
1379 time only file timestamp changed
1381 *v:fcs_choice* *fcs_choice-variable*
1382 v:fcs_choice What should happen after a |FileChangedShell| event was
1383 triggered. Can be used in an autocommand to tell Vim what to
1384 do with the affected buffer:
1385 reload Reload the buffer (does not work if
1386 the file was deleted).
1387 ask Ask the user what to do, as if there
1388 was no autocommand. Except that when
1389 only the timestamp changed nothing
1390 will happen.
1391 <empty> Nothing, the autocommand should do
1392 everything that needs to be done.
1393 The default is empty. If another (invalid) value is used then
1394 Vim behaves like it is empty, there is no warning message.
1396 *v:fname_in* *fname_in-variable*
1397 v:fname_in The name of the input file. Valid while evaluating:
1398 option used for ~
1399 'charconvert' file to be converted
1400 'diffexpr' original file
1401 'patchexpr' original file
1402 'printexpr' file to be printed
1403 And set to the swap file name for |SwapExists|.
1405 *v:fname_out* *fname_out-variable*
1406 v:fname_out The name of the output file. Only valid while
1407 evaluating:
1408 option used for ~
1409 'charconvert' resulting converted file (*)
1410 'diffexpr' output of diff
1411 'patchexpr' resulting patched file
1412 (*) When doing conversion for a write command (e.g., ":w
1413 file") it will be equal to v:fname_in. When doing conversion
1414 for a read command (e.g., ":e file") it will be a temporary
1415 file and different from v:fname_in.
1417 *v:fname_new* *fname_new-variable*
1418 v:fname_new The name of the new version of the file. Only valid while
1419 evaluating 'diffexpr'.
1421 *v:fname_diff* *fname_diff-variable*
1422 v:fname_diff The name of the diff (patch) file. Only valid while
1423 evaluating 'patchexpr'.
1425 *v:folddashes* *folddashes-variable*
1426 v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed
1427 fold.
1428 Read-only in the |sandbox|. |fold-foldtext|
1430 *v:foldlevel* *foldlevel-variable*
1431 v:foldlevel Used for 'foldtext': foldlevel of closed fold.
1432 Read-only in the |sandbox|. |fold-foldtext|
1434 *v:foldend* *foldend-variable*
1435 v:foldend Used for 'foldtext': last line of closed fold.
1436 Read-only in the |sandbox|. |fold-foldtext|
1438 *v:foldstart* *foldstart-variable*
1439 v:foldstart Used for 'foldtext': first line of closed fold.
1440 Read-only in the |sandbox|. |fold-foldtext|
1442 *v:insertmode* *insertmode-variable*
1443 v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand
1444 events. Values:
1445 i Insert mode
1446 r Replace mode
1447 v Virtual Replace mode
1449 *v:key* *key-variable*
1450 v:key Key of the current item of a |Dictionary|. Only valid while
1451 evaluating the expression used with |map()| and |filter()|.
1452 Read-only.
1454 *v:lang* *lang-variable*
1455 v:lang The current locale setting for messages of the runtime
1456 environment. This allows Vim scripts to be aware of the
1457 current language. Technical: it's the value of LC_MESSAGES.
1458 The value is system dependent.
1459 This variable can not be set directly, use the |:language|
1460 command.
1461 It can be different from |v:ctype| when messages are desired
1462 in a different language than what is used for character
1463 encoding. See |multi-lang|.
1465 *v:lc_time* *lc_time-variable*
1466 v:lc_time The current locale setting for time messages of the runtime
1467 environment. This allows Vim scripts to be aware of the
1468 current language. Technical: it's the value of LC_TIME.
1469 This variable can not be set directly, use the |:language|
1470 command. See |multi-lang|.
1472 *v:lnum* *lnum-variable*
1473 v:lnum Line number for the 'foldexpr' |fold-expr| and 'indentexpr'
1474 expressions, tab page number for 'guitablabel' and
1475 'guitabtooltip'. Only valid while one of these expressions is
1476 being evaluated. Read-only when in the |sandbox|.
1478 *v:mouse_win* *mouse_win-variable*
1479 v:mouse_win Window number for a mouse click obtained with |getchar()|.
1480 First window has number 1, like with |winnr()|. The value is
1481 zero when there was no mouse button click.
1483 *v:mouse_lnum* *mouse_lnum-variable*
1484 v:mouse_lnum Line number for a mouse click obtained with |getchar()|.
1485 This is the text line number, not the screen line number. The
1486 value is zero when there was no mouse button click.
1488 *v:mouse_col* *mouse_col-variable*
1489 v:mouse_col Column number for a mouse click obtained with |getchar()|.
1490 This is the screen column number, like with |virtcol()|. The
1491 value is zero when there was no mouse button click.
1493 *v:oldfiles* *oldfiles-variable*
1494 v:oldfiles List of file names that is loaded from the |viminfo| file on
1495 startup. These are the files that Vim remembers marks for.
1496 The length of the List is limited by the ' argument of the
1497 'viminfo' option (default is 100).
1498 Also see |:oldfiles| and |c_#<|.
1499 The List can be modified, but this has no effect on what is
1500 stored in the |viminfo| file later. If you use values other
1501 than String this will cause trouble.
1502 {only when compiled with the +viminfo feature}
1504 *v:operator* *operator-variable*
1505 v:operator The last operator given in Normal mode. This is a single
1506 character except for commands starting with <g> or <z>,
1507 in which case it is two characters. Best used alongside
1508 |v:prevcount| and |v:register|. Useful if you want to cancel
1509 Operator-pending mode and then use the operator, e.g.: >
1510 :omap O <Esc>:call MyMotion(v:operator)<CR>
1511 < The value remains set until another operator is entered, thus
1512 don't expect it to be empty.
1513 v:operator is not set for |:delete|, |:yank| or other Ex
1514 commands.
1515 Read-only.
1517 *v:prevcount* *prevcount-variable*
1518 v:prevcount The count given for the last but one Normal mode command.
1519 This is the v:count value of the previous command. Useful if
1520 you want to cancel Visual or Operator-pending mode and then
1521 use the count, e.g.: >
1522 :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
1523 < Read-only.
1525 *v:profiling* *profiling-variable*
1526 v:profiling Normally zero. Set to one after using ":profile start".
1527 See |profiling|.
1529 *v:progname* *progname-variable*
1530 v:progname Contains the name (with path removed) with which Vim was
1531 invoked. Allows you to do special initialisations for "view",
1532 "evim" etc., or any other name you might symlink to Vim.
1533 Read-only.
1535 *v:register* *register-variable*
1536 v:register The name of the register supplied to the last normal mode
1537 command. Empty if none were supplied. |getreg()| |setreg()|
1539 *v:scrollstart* *scrollstart-variable*
1540 v:scrollstart String describing the script or function that caused the
1541 screen to scroll up. It's only set when it is empty, thus the
1542 first reason is remembered. It is set to "Unknown" for a
1543 typed command.
1544 This can be used to find out why your script causes the
1545 hit-enter prompt.
1547 *v:servername* *servername-variable*
1548 v:servername The resulting registered |x11-clientserver| name if any.
1549 Read-only.
1552 v:searchforward *v:searchforward* *searchforward-variable*
1553 Search direction: 1 after a forward search, 0 after a
1554 backward search. It is reset to forward when directly setting
1555 the last search pattern, see |quote/|.
1556 Note that the value is restored when returning from a
1557 function. |function-search-undo|.
1558 Read-write.
1560 *v:shell_error* *shell_error-variable*
1561 v:shell_error Result of the last shell command. When non-zero, the last
1562 shell command had an error. When zero, there was no problem.
1563 This only works when the shell returns the error code to Vim.
1564 The value -1 is often used when the command could not be
1565 executed. Read-only.
1566 Example: >
1567 :!mv foo bar
1568 :if v:shell_error
1569 : echo 'could not rename "foo" to "bar"!'
1570 :endif
1571 < "shell_error" also works, for backwards compatibility.
1573 *v:statusmsg* *statusmsg-variable*
1574 v:statusmsg Last given status message. It's allowed to set this variable.
1576 *v:swapname* *swapname-variable*
1577 v:swapname Only valid when executing |SwapExists| autocommands: Name of
1578 the swap file found. Read-only.
1580 *v:swapchoice* *swapchoice-variable*
1581 v:swapchoice |SwapExists| autocommands can set this to the selected choice
1582 for handling an existing swap file:
1583 'o' Open read-only
1584 'e' Edit anyway
1585 'r' Recover
1586 'd' Delete swapfile
1587 'q' Quit
1588 'a' Abort
1589 The value should be a single-character string. An empty value
1590 results in the user being asked, as would happen when there is
1591 no SwapExists autocommand. The default is empty.
1593 *v:swapcommand* *swapcommand-variable*
1594 v:swapcommand Normal mode command to be executed after a file has been
1595 opened. Can be used for a |SwapExists| autocommand to have
1596 another Vim open the file and jump to the right place. For
1597 example, when jumping to a tag the value is ":tag tagname\r".
1598 For ":edit +cmd file" the value is ":cmd\r".
1600 *v:termresponse* *termresponse-variable*
1601 v:termresponse The escape sequence returned by the terminal for the |t_RV|
1602 termcap entry. It is set when Vim receives an escape sequence
1603 that starts with ESC [ or CSI and ends in a 'c', with only
1604 digits, ';' and '.' in between.
1605 When this option is set, the TermResponse autocommand event is
1606 fired, so that you can react to the response from the
1607 terminal.
1608 The response from a new xterm is: "<Esc>[ Pp ; Pv ; Pc c". Pp
1609 is the terminal type: 0 for vt100 and 1 for vt220. Pv is the
1610 patch level (since this was introduced in patch 95, it's
1611 always 95 or bigger). Pc is always zero.
1612 {only when compiled with |+termresponse| feature}
1614 *v:this_session* *this_session-variable*
1615 v:this_session Full filename of the last loaded or saved session file. See
1616 |:mksession|. It is allowed to set this variable. When no
1617 session file has been saved, this variable is empty.
1618 "this_session" also works, for backwards compatibility.
1620 *v:throwpoint* *throwpoint-variable*
1621 v:throwpoint The point where the exception most recently caught and not
1622 finished was thrown. Not set when commands are typed. See
1623 also |v:exception| and |throw-variables|.
1624 Example: >
1625 :try
1626 : throw "oops"
1627 :catch /.*/
1628 : echo "Exception from" v:throwpoint
1629 :endtry
1630 < Output: "Exception from test.vim, line 2"
1632 *v:val* *val-variable*
1633 v:val Value of the current item of a |List| or |Dictionary|. Only
1634 valid while evaluating the expression used with |map()| and
1635 |filter()|. Read-only.
1637 *v:version* *version-variable*
1638 v:version Version number of Vim: Major version number times 100 plus
1639 minor version number. Version 5.0 is 500. Version 5.1 (5.01)
1640 is 501. Read-only. "version" also works, for backwards
1641 compatibility.
1642 Use |has()| to check if a certain patch was included, e.g.: >
1643 if has("patch123")
1644 < Note that patch numbers are specific to the version, thus both
1645 version 5.0 and 5.1 may have a patch 123, but these are
1646 completely different.
1648 *v:warningmsg* *warningmsg-variable*
1649 v:warningmsg Last given warning message. It's allowed to set this variable.
1651 ==============================================================================
1652 4. Builtin Functions *functions*
1654 See |function-list| for a list grouped by what the function is used for.
1656 (Use CTRL-] on the function name to jump to the full explanation.)
1658 USAGE RESULT DESCRIPTION ~
1660 abs( {expr}) Float or Number absolute value of {expr}
1661 add( {list}, {item}) List append {item} to |List| {list}
1662 append( {lnum}, {string}) Number append {string} below line {lnum}
1663 append( {lnum}, {list}) Number append lines {list} below line {lnum}
1664 argc() Number number of files in the argument list
1665 argidx() Number current index in the argument list
1666 argv( {nr}) String {nr} entry of the argument list
1667 argv( ) List the argument list
1668 atan( {expr}) Float arc tangent of {expr}
1669 browse( {save}, {title}, {initdir}, {default})
1670 String put up a file requester
1671 browsedir( {title}, {initdir}) String put up a directory requester
1672 bufexists( {expr}) Number TRUE if buffer {expr} exists
1673 buflisted( {expr}) Number TRUE if buffer {expr} is listed
1674 bufloaded( {expr}) Number TRUE if buffer {expr} is loaded
1675 bufname( {expr}) String Name of the buffer {expr}
1676 bufnr( {expr}) Number Number of the buffer {expr}
1677 bufwinnr( {expr}) Number window number of buffer {expr}
1678 byte2line( {byte}) Number line number at byte count {byte}
1679 byteidx( {expr}, {nr}) Number byte index of {nr}'th char in {expr}
1680 call( {func}, {arglist} [, {dict}])
1681 any call {func} with arguments {arglist}
1682 ceil( {expr}) Float round {expr} up
1683 changenr() Number current change number
1684 char2nr( {expr}) Number ASCII value of first char in {expr}
1685 cindent( {lnum}) Number C indent for line {lnum}
1686 clearmatches() none clear all matches
1687 col( {expr}) Number column nr of cursor or mark
1688 complete( {startcol}, {matches}) none set Insert mode completion
1689 complete_add( {expr}) Number add completion match
1690 complete_check() Number check for key typed during completion
1691 confirm( {msg} [, {choices} [, {default} [, {type}]]])
1692 Number number of choice picked by user
1693 copy( {expr}) any make a shallow copy of {expr}
1694 cos( {expr}) Float cosine of {expr}
1695 count( {list}, {expr} [, {start} [, {ic}]])
1696 Number count how many {expr} are in {list}
1697 cscope_connection( [{num} , {dbpath} [, {prepend}]])
1698 Number checks existence of cscope connection
1699 cursor( {lnum}, {col} [, {coladd}])
1700 Number move cursor to {lnum}, {col}, {coladd}
1701 cursor( {list}) Number move cursor to position in {list}
1702 deepcopy( {expr}) any make a full copy of {expr}
1703 delete( {fname}) Number delete file {fname}
1704 did_filetype() Number TRUE if FileType autocommand event used
1705 diff_filler( {lnum}) Number diff filler lines about {lnum}
1706 diff_hlID( {lnum}, {col}) Number diff highlighting at {lnum}/{col}
1707 empty( {expr}) Number TRUE if {expr} is empty
1708 escape( {string}, {chars}) String escape {chars} in {string} with '\'
1709 eval( {string}) any evaluate {string} into its value
1710 eventhandler( ) Number TRUE if inside an event handler
1711 executable( {expr}) Number 1 if executable {expr} exists
1712 exists( {expr}) Number TRUE if {expr} exists
1713 extend( {expr1}, {expr2} [, {expr3}])
1714 List/Dict insert items of {expr2} into {expr1}
1715 expand( {expr} [, {flag}]) String expand special keywords in {expr}
1716 feedkeys( {string} [, {mode}]) Number add key sequence to typeahead buffer
1717 filereadable( {file}) Number TRUE if {file} is a readable file
1718 filewritable( {file}) Number TRUE if {file} is a writable file
1719 filter( {expr}, {string}) List/Dict remove items from {expr} where
1720 {string} is 0
1721 finddir( {name}[, {path}[, {count}]])
1722 String find directory {name} in {path}
1723 findfile( {name}[, {path}[, {count}]])
1724 String find file {name} in {path}
1725 float2nr( {expr}) Number convert Float {expr} to a Number
1726 floor( {expr}) Float round {expr} down
1727 fnameescape( {fname}) String escape special characters in {fname}
1728 fnamemodify( {fname}, {mods}) String modify file name
1729 foldclosed( {lnum}) Number first line of fold at {lnum} if closed
1730 foldclosedend( {lnum}) Number last line of fold at {lnum} if closed
1731 foldlevel( {lnum}) Number fold level at {lnum}
1732 foldtext( ) String line displayed for closed fold
1733 foldtextresult( {lnum}) String text for closed fold at {lnum}
1734 foreground( ) Number bring the Vim window to the foreground
1735 function( {name}) Funcref reference to function {name}
1736 garbagecollect( [at_exit]) none free memory, breaking cyclic references
1737 get( {list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
1738 get( {dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
1739 getbufline( {expr}, {lnum} [, {end}])
1740 List lines {lnum} to {end} of buffer {expr}
1741 getbufvar( {expr}, {varname}) any variable {varname} in buffer {expr}
1742 getchar( [expr]) Number get one character from the user
1743 getcharmod( ) Number modifiers for the last typed character
1744 getcmdline() String return the current command-line
1745 getcmdpos() Number return cursor position in command-line
1746 getcmdtype() String return the current command-line type
1747 getcwd() String the current working directory
1748 getfperm( {fname}) String file permissions of file {fname}
1749 getfsize( {fname}) Number size in bytes of file {fname}
1750 getfontname( [{name}]) String name of font being used
1751 getftime( {fname}) Number last modification time of file
1752 getftype( {fname}) String description of type of file {fname}
1753 getline( {lnum}) String line {lnum} of current buffer
1754 getline( {lnum}, {end}) List lines {lnum} to {end} of current buffer
1755 getloclist( {nr}) List list of location list items
1756 getmatches() List list of current matches
1757 getpid() Number process ID of Vim
1758 getpos( {expr}) List position of cursor, mark, etc.
1759 getqflist() List list of quickfix items
1760 getreg( [{regname} [, 1]]) String contents of register
1761 getregtype( [{regname}]) String type of register
1762 gettabwinvar( {tabnr}, {winnr}, {name})
1763 any {name} in {winnr} in tab page {tabnr}
1764 getwinposx() Number X coord in pixels of GUI Vim window
1765 getwinposy() Number Y coord in pixels of GUI Vim window
1766 getwinvar( {nr}, {varname}) any variable {varname} in window {nr}
1767 glob( {expr} [, {flag}]) String expand file wildcards in {expr}
1768 globpath( {path}, {expr} [, {flag}])
1769 String do glob({expr}) for all dirs in {path}
1770 has( {feature}) Number TRUE if feature {feature} supported
1771 has_key( {dict}, {key}) Number TRUE if {dict} has entry {key}
1772 haslocaldir() Number TRUE if current window executed |:lcd|
1773 hasmapto( {what} [, {mode} [, {abbr}]])
1774 Number TRUE if mapping to {what} exists
1775 histadd( {history},{item}) String add an item to a history
1776 histdel( {history} [, {item}]) String remove an item from a history
1777 histget( {history} [, {index}]) String get the item {index} from a history
1778 histnr( {history}) Number highest index of a history
1779 hlexists( {name}) Number TRUE if highlight group {name} exists
1780 hlID( {name}) Number syntax ID of highlight group {name}
1781 hostname() String name of the machine Vim is running on
1782 iconv( {expr}, {from}, {to}) String convert encoding of {expr}
1783 indent( {lnum}) Number indent of line {lnum}
1784 index( {list}, {expr} [, {start} [, {ic}]])
1785 Number index in {list} where {expr} appears
1786 input( {prompt} [, {text} [, {completion}]])
1787 String get input from the user
1788 inputdialog( {p} [, {t} [, {c}]]) String like input() but in a GUI dialog
1789 inputlist( {textlist}) Number let the user pick from a choice list
1790 inputrestore() Number restore typeahead
1791 inputsave() Number save and clear typeahead
1792 inputsecret( {prompt} [, {text}]) String like input() but hiding the text
1793 insert( {list}, {item} [, {idx}]) List insert {item} in {list} [before {idx}]
1794 isdirectory( {directory}) Number TRUE if {directory} is a directory
1795 islocked( {expr}) Number TRUE if {expr} is locked
1796 items( {dict}) List key-value pairs in {dict}
1797 join( {list} [, {sep}]) String join {list} items into one String
1798 keys( {dict}) List keys in {dict}
1799 len( {expr}) Number the length of {expr}
1800 libcall( {lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
1801 libcallnr( {lib}, {func}, {arg}) Number idem, but return a Number
1802 line( {expr}) Number line nr of cursor, last line or mark
1803 line2byte( {lnum}) Number byte count of line {lnum}
1804 lispindent( {lnum}) Number Lisp indent for line {lnum}
1805 localtime() Number current time
1806 log10( {expr}) Float logarithm of Float {expr} to base 10
1807 map( {expr}, {string}) List/Dict change each item in {expr} to {expr}
1808 maparg( {name}[, {mode} [, {abbr}]])
1809 String rhs of mapping {name} in mode {mode}
1810 mapcheck( {name}[, {mode} [, {abbr}]])
1811 String check for mappings matching {name}
1812 match( {expr}, {pat}[, {start}[, {count}]])
1813 Number position where {pat} matches in {expr}
1814 matchadd( {group}, {pattern}[, {priority}[, {id}]])
1815 Number highlight {pattern} with {group}
1816 matcharg( {nr}) List arguments of |:match|
1817 matchdelete( {id}) Number delete match identified by {id}
1818 matchend( {expr}, {pat}[, {start}[, {count}]])
1819 Number position where {pat} ends in {expr}
1820 matchlist( {expr}, {pat}[, {start}[, {count}]])
1821 List match and submatches of {pat} in {expr}
1822 matchstr( {expr}, {pat}[, {start}[, {count}]])
1823 String {count}'th match of {pat} in {expr}
1824 max( {list}) Number maximum value of items in {list}
1825 min( {list}) Number minimum value of items in {list}
1826 mkdir( {name} [, {path} [, {prot}]])
1827 Number create directory {name}
1828 mode( [expr]) String current editing mode
1829 mzeval( {expr}) any evaluate |MzScheme| expression
1830 nextnonblank( {lnum}) Number line nr of non-blank line >= {lnum}
1831 nr2char( {expr}) String single char with ASCII value {expr}
1832 pathshorten( {expr}) String shorten directory names in a path
1833 pow( {x}, {y}) Float {x} to the power of {y}
1834 prevnonblank( {lnum}) Number line nr of non-blank line <= {lnum}
1835 printf( {fmt}, {expr1}...) String format text
1836 pumvisible() Number whether popup menu is visible
1837 range( {expr} [, {max} [, {stride}]])
1838 List items from {expr} to {max}
1839 readfile( {fname} [, {binary} [, {max}]])
1840 List get list of lines from file {fname}
1841 reltime( [{start} [, {end}]]) List get time value
1842 reltimestr( {time}) String turn time value into a String
1843 remote_expr( {server}, {string} [, {idvar}])
1844 String send expression
1845 remote_foreground( {server}) Number bring Vim server to the foreground
1846 remote_peek( {serverid} [, {retvar}])
1847 Number check for reply string
1848 remote_read( {serverid}) String read reply string
1849 remote_send( {server}, {string} [, {idvar}])
1850 String send key sequence
1851 remove( {list}, {idx} [, {end}]) any remove items {idx}-{end} from {list}
1852 remove( {dict}, {key}) any remove entry {key} from {dict}
1853 rename( {from}, {to}) Number rename (move) file from {from} to {to}
1854 repeat( {expr}, {count}) String repeat {expr} {count} times
1855 resolve( {filename}) String get filename a shortcut points to
1856 reverse( {list}) List reverse {list} in-place
1857 round( {expr}) Float round off {expr}
1858 search( {pattern} [, {flags} [, {stopline} [, {timeout}]]])
1859 Number search for {pattern}
1860 searchdecl( {name} [, {global} [, {thisblock}]])
1861 Number search for variable declaration
1862 searchpair( {start}, {middle}, {end} [, {flags} [, {skip} [...]]])
1863 Number search for other end of start/end pair
1864 searchpairpos( {start}, {middle}, {end} [, {flags} [, {skip} [...]]])
1865 List search for other end of start/end pair
1866 searchpos( {pattern} [, {flags} [, {stopline} [, {timeout}]]])
1867 List search for {pattern}
1868 server2client( {clientid}, {string})
1869 Number send reply string
1870 serverlist() String get a list of available servers
1871 setbufvar( {expr}, {varname}, {val}) set {varname} in buffer {expr} to {val}
1872 setcmdpos( {pos}) Number set cursor position in command-line
1873 setline( {lnum}, {line}) Number set line {lnum} to {line}
1874 setloclist( {nr}, {list}[, {action}])
1875 Number modify location list using {list}
1876 setmatches( {list}) Number restore a list of matches
1877 setpos( {expr}, {list}) Number set the {expr} position to {list}
1878 setqflist( {list}[, {action}]) Number modify quickfix list using {list}
1879 setreg( {n}, {v}[, {opt}]) Number set register to value and type
1880 settabwinvar( {tabnr}, {winnr}, {varname}, {val}) set {varname} in window
1881 {winnr} in tab page {tabnr} to {val}
1882 setwinvar( {nr}, {varname}, {val}) set {varname} in window {nr} to {val}
1883 shellescape( {string} [, {special}])
1884 String escape {string} for use as shell
1885 command argument
1886 simplify( {filename}) String simplify filename as much as possible
1887 sin( {expr}) Float sine of {expr}
1888 sort( {list} [, {func}]) List sort {list}, using {func} to compare
1889 soundfold( {word}) String sound-fold {word}
1890 spellbadword() String badly spelled word at cursor
1891 spellsuggest( {word} [, {max} [, {capital}]])
1892 List spelling suggestions
1893 split( {expr} [, {pat} [, {keepempty}]])
1894 List make |List| from {pat} separated {expr}
1895 sqrt( {expr} Float squar root of {expr}
1896 str2float( {expr}) Float convert String to Float
1897 str2nr( {expr} [, {base}]) Number convert String to Number
1898 strftime( {format}[, {time}]) String time in specified format
1899 stridx( {haystack}, {needle}[, {start}])
1900 Number index of {needle} in {haystack}
1901 string( {expr}) String String representation of {expr} value
1902 strlen( {expr}) Number length of the String {expr}
1903 strpart( {src}, {start}[, {len}])
1904 String {len} characters of {src} at {start}
1905 strridx( {haystack}, {needle} [, {start}])
1906 Number last index of {needle} in {haystack}
1907 strtrans( {expr}) String translate string to make it printable
1908 submatch( {nr}) String specific match in ":substitute"
1909 substitute( {expr}, {pat}, {sub}, {flags})
1910 String all {pat} in {expr} replaced with {sub}
1911 synID( {lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
1912 synIDattr( {synID}, {what} [, {mode}])
1913 String attribute {what} of syntax ID {synID}
1914 synIDtrans( {synID}) Number translated syntax ID of {synID}
1915 synstack( {lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
1916 system( {expr} [, {input}]) String output of shell command/filter {expr}
1917 tabpagebuflist( [{arg}]) List list of buffer numbers in tab page
1918 tabpagenr( [{arg}]) Number number of current or last tab page
1919 tabpagewinnr( {tabarg}[, {arg}])
1920 Number number of current window in tab page
1921 taglist( {expr}) List list of tags matching {expr}
1922 tagfiles() List tags files used
1923 tempname() String name for a temporary file
1924 tolower( {expr}) String the String {expr} switched to lowercase
1925 toupper( {expr}) String the String {expr} switched to uppercase
1926 tr( {src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
1927 to chars in {tostr}
1928 trunc( {expr} Float truncate Float {expr}
1929 type( {name}) Number type of variable {name}
1930 values( {dict}) List values in {dict}
1931 virtcol( {expr}) Number screen column of cursor or mark
1932 visualmode( [expr]) String last visual mode used
1933 winbufnr( {nr}) Number buffer number of window {nr}
1934 wincol() Number window column of the cursor
1935 winheight( {nr}) Number height of window {nr}
1936 winline() Number window line of the cursor
1937 winnr( [{expr}]) Number number of current window
1938 winrestcmd() String returns command to restore window sizes
1939 winrestview( {dict}) none restore view of current window
1940 winsaveview() Dict save view of current window
1941 winwidth( {nr}) Number width of window {nr}
1942 writefile( {list}, {fname} [, {binary}])
1943 Number write list of lines to file {fname}
1945 abs({expr}) *abs()*
1946 Return the absolute value of {expr}. When {expr} evaluates to
1947 a |Float| abs() returns a |Float|. When {expr} can be
1948 converted to a |Number| abs() returns a |Number|. Otherwise
1949 abs() gives an error message and returns -1.
1950 Examples: >
1951 echo abs(1.456)
1952 < 1.456 >
1953 echo abs(-5.456)
1954 < 5.456 >
1955 echo abs(-4)
1956 < 4
1957 {only available when compiled with the |+float| feature}
1959 acos({expr}) *acos()*
1960 Return the arc cosine of {expr} measured in radians, as a
1961 |Float|in the range of [0,pi].
1962 {expr} must evaluate to a|Float|or a|Number|in [-1,1].
1963 Examples: >
1964 :echo acos(0)
1965 < 1.570796 >
1966 :echo acos(-0.5)
1967 < 2.094395
1968 {only available when compiled with|+float|and extention}
1970 add({list}, {expr}) *add()*
1971 Append the item {expr} to |List| {list}. Returns the
1972 resulting |List|. Examples: >
1973 :let alist = add([1, 2, 3], item)
1974 :call add(mylist, "woodstock")
1975 < Note that when {expr} is a |List| it is appended as a single
1976 item. Use |extend()| to concatenate |Lists|.
1977 Use |insert()| to add an item at another position.
1980 append({lnum}, {expr}) *append()*
1981 When {expr} is a |List|: Append each item of the |List| as a
1982 text line below line {lnum} in the current buffer.
1983 Otherwise append {expr} as one text line below line {lnum} in
1984 the current buffer.
1985 {lnum} can be zero to insert a line before the first one.
1986 Returns 1 for failure ({lnum} out of range or out of memory),
1987 0 for success. Example: >
1988 :let failed = append(line('$'), "# THE END")
1989 :let failed = append(0, ["Chapter 1", "the beginning"])
1990 <
1991 *argc()*
1992 argc() The result is the number of files in the argument list of the
1993 current window. See |arglist|.
1995 *argidx()*
1996 argidx() The result is the current index in the argument list. 0 is
1997 the first file. argc() - 1 is the last one. See |arglist|.
1999 *argv()*
2000 argv([{nr}]) The result is the {nr}th file in the argument list of the
2001 current window. See |arglist|. "argv(0)" is the first one.
2002 Example: >
2003 :let i = 0
2004 :while i < argc()
2005 : let f = escape(fnameescape(argv(i)), '.')
2006 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>'
2007 : let i = i + 1
2008 :endwhile
2009 < Without the {nr} argument a |List| with the whole |arglist| is
2010 returned.
2012 asin({expr}) *asin()*
2013 Return the arc sine of {expr} measured in radians, as a|Float|
2014 in the range of [-pi/2,pi/2].
2015 {expr} must evaluate to a|Float|or a|Number|in [-1,1].
2016 Examples: >
2017 :echo asin(0.8)
2018 < 0.927295 >
2019 :echo asin(-0.5)
2020 < -0.523599
2021 {only available when compiled with|+float|and extention}
2023 atan({expr}) *atan()*
2024 Return the principal value of the arc tangent of {expr}, in
2025 the range [-pi/2, +pi/2] radians, as a |Float|.
2026 {expr} must evaluate to a |Float| or a |Number|.
2027 Examples: >
2028 :echo atan(100)
2029 < 1.560797 >
2030 :echo atan(-4.01)
2031 < -1.326405
2032 {only available when compiled with the |+float| feature}
2034 atan2({expr1},{expr2}) *atan2()*
2035 Return the arc tangent of {expr1}/{expr2}, measured in radians,
2036 as a|Float|in the range [-pi,pi].
2037 {expr1} and {expr2} must evaluate to a|Float|or a|Number|.
2038 Examples: >
2039 :echo atan2(-1,1)
2040 < -0.785398 >
2041 :echo atan2(1,-1)
2042 < 2.356194
2043 {only available when compiled with|+float|and extention}
2045 *browse()*
2046 browse({save}, {title}, {initdir}, {default})
2047 Put up a file requester. This only works when "has("browse")"
2048 returns non-zero (only in some GUI versions).
2049 The input fields are:
2050 {save} when non-zero, select file to write
2051 {title} title for the requester
2052 {initdir} directory to start browsing in
2053 {default} default file name
2054 When the "Cancel" button is hit, something went wrong, or
2055 browsing is not possible, an empty string is returned.
2057 *browsedir()*
2058 browsedir({title}, {initdir})
2059 Put up a directory requester. This only works when
2060 "has("browse")" returns non-zero (only in some GUI versions).
2061 On systems where a directory browser is not supported a file
2062 browser is used. In that case: select a file in the directory
2063 to be used.
2064 The input fields are:
2065 {title} title for the requester
2066 {initdir} directory to start browsing in
2067 When the "Cancel" button is hit, something went wrong, or
2068 browsing is not possible, an empty string is returned.
2070 bufexists({expr}) *bufexists()*
2071 The result is a Number, which is non-zero if a buffer called
2072 {expr} exists.
2073 If the {expr} argument is a number, buffer numbers are used.
2074 If the {expr} argument is a string it must match a buffer name
2075 exactly. The name can be:
2076 - Relative to the current directory.
2077 - A full path.
2078 - The name of a buffer with 'buftype' set to "nofile".
2079 - A URL name.
2080 Unlisted buffers will be found.
2081 Note that help files are listed by their short name in the
2082 output of |:buffers|, but bufexists() requires using their
2083 long name to be able to find them.
2084 bufexists() may report a buffer exists, but to use the name
2085 with a |:buffer| command you may need to use |expand()|. Esp
2086 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
2087 Use "bufexists(0)" to test for the existence of an alternate
2088 file name.
2089 *buffer_exists()*
2090 Obsolete name: buffer_exists().
2092 buflisted({expr}) *buflisted()*
2093 The result is a Number, which is non-zero if a buffer called
2094 {expr} exists and is listed (has the 'buflisted' option set).
2095 The {expr} argument is used like with |bufexists()|.
2097 bufloaded({expr}) *bufloaded()*
2098 The result is a Number, which is non-zero if a buffer called
2099 {expr} exists and is loaded (shown in a window or hidden).
2100 The {expr} argument is used like with |bufexists()|.
2102 bufname({expr}) *bufname()*
2103 The result is the name of a buffer, as it is displayed by the
2104 ":ls" command.
2105 If {expr} is a Number, that buffer number's name is given.
2106 Number zero is the alternate buffer for the current window.
2107 If {expr} is a String, it is used as a |file-pattern| to match
2108 with the buffer names. This is always done like 'magic' is
2109 set and 'cpoptions' is empty. When there is more than one
2110 match an empty string is returned.
2111 "" or "%" can be used for the current buffer, "#" for the
2112 alternate buffer.
2113 A full match is preferred, otherwise a match at the start, end
2114 or middle of the buffer name is accepted. If you only want a
2115 full match then put "^" at the start and "$" at the end of the
2116 pattern.
2117 Listed buffers are found first. If there is a single match
2118 with a listed buffer, that one is returned. Next unlisted
2119 buffers are searched for.
2120 If the {expr} is a String, but you want to use it as a buffer
2121 number, force it to be a Number by adding zero to it: >
2122 :echo bufname("3" + 0)
2123 < If the buffer doesn't exist, or doesn't have a name, an empty
2124 string is returned. >
2125 bufname("#") alternate buffer name
2126 bufname(3) name of buffer 3
2127 bufname("%") name of current buffer
2128 bufname("file2") name of buffer where "file2" matches.
2129 < *buffer_name()*
2130 Obsolete name: buffer_name().
2132 *bufnr()*
2133 bufnr({expr} [, {create}])
2134 The result is the number of a buffer, as it is displayed by
2135 the ":ls" command. For the use of {expr}, see |bufname()|
2136 above.
2137 If the buffer doesn't exist, -1 is returned. Or, if the
2138 {create} argument is present and not zero, a new, unlisted,
2139 buffer is created and its number is returned.
2140 bufnr("$") is the last buffer: >
2141 :let last_buffer = bufnr("$")
2142 < The result is a Number, which is the highest buffer number
2143 of existing buffers. Note that not all buffers with a smaller
2144 number necessarily exist, because ":bwipeout" may have removed
2145 them. Use bufexists() to test for the existence of a buffer.
2146 *buffer_number()*
2147 Obsolete name: buffer_number().
2148 *last_buffer_nr()*
2149 Obsolete name for bufnr("$"): last_buffer_nr().
2151 bufwinnr({expr}) *bufwinnr()*
2152 The result is a Number, which is the number of the first
2153 window associated with buffer {expr}. For the use of {expr},
2154 see |bufname()| above. If buffer {expr} doesn't exist or
2155 there is no such window, -1 is returned. Example: >
2157 echo "A window containing buffer 1 is " . (bufwinnr(1))
2159 < The number can be used with |CTRL-W_w| and ":wincmd w"
2160 |:wincmd|.
2161 Only deals with the current tab page.
2164 byte2line({byte}) *byte2line()*
2165 Return the line number that contains the character at byte
2166 count {byte} in the current buffer. This includes the
2167 end-of-line character, depending on the 'fileformat' option
2168 for the current buffer. The first character has byte count
2169 one.
2170 Also see |line2byte()|, |go| and |:goto|.
2171 {not available when compiled without the |+byte_offset|
2172 feature}
2174 byteidx({expr}, {nr}) *byteidx()*
2175 Return byte index of the {nr}'th character in the string
2176 {expr}. Use zero for the first character, it returns zero.
2177 This function is only useful when there are multibyte
2178 characters, otherwise the returned value is equal to {nr}.
2179 Composing characters are counted as a separate character.
2180 Example : >
2181 echo matchstr(str, ".", byteidx(str, 3))
2182 < will display the fourth character. Another way to do the
2183 same: >
2184 let s = strpart(str, byteidx(str, 3))
2185 echo strpart(s, 0, byteidx(s, 1))
2186 < If there are less than {nr} characters -1 is returned.
2187 If there are exactly {nr} characters the length of the string
2188 is returned.
2190 call({func}, {arglist} [, {dict}]) *call()* *E699*
2191 Call function {func} with the items in |List| {arglist} as
2192 arguments.
2193 {func} can either be a |Funcref| or the name of a function.
2194 a:firstline and a:lastline are set to the cursor line.
2195 Returns the return value of the called function.
2196 {dict} is for functions with the "dict" attribute. It will be
2197 used to set the local variable "self". |Dictionary-function|
2199 ceil({expr}) *ceil()*
2200 Return the smallest integral value greater than or equal to
2201 {expr} as a |Float| (round up).
2202 {expr} must evaluate to a |Float| or a |Number|.
2203 Examples: >
2204 echo ceil(1.456)
2205 < 2.0 >
2206 echo ceil(-5.456)
2207 < -5.0 >
2208 echo ceil(4.0)
2209 < 4.0
2210 {only available when compiled with the |+float| feature}
2212 changenr() *changenr()*
2213 Return the number of the most recent change. This is the same
2214 number as what is displayed with |:undolist| and can be used
2215 with the |:undo| command.
2216 When a change was made it is the number of that change. After
2217 redo it is the number of the redone change. After undo it is
2218 one less than the number of the undone change.
2220 char2nr({expr}) *char2nr()*
2221 Return number value of the first char in {expr}. Examples: >
2222 char2nr(" ") returns 32
2223 char2nr("ABC") returns 65
2224 < The current 'encoding' is used. Example for "utf-8": >
2225 char2nr("á") returns 225
2226 char2nr("á"[0]) returns 195
2227 < |nr2char()| does the opposite.
2229 cindent({lnum}) *cindent()*
2230 Get the amount of indent for line {lnum} according the C
2231 indenting rules, as with 'cindent'.
2232 The indent is counted in spaces, the value of 'tabstop' is
2233 relevant. {lnum} is used just like in |getline()|.
2234 When {lnum} is invalid or Vim was not compiled the |+cindent|
2235 feature, -1 is returned.
2236 See |C-indenting|.
2238 clearmatches() *clearmatches()*
2239 Clears all matches previously defined by |matchadd()| and the
2240 |:match| commands.
2242 *col()*
2243 col({expr}) The result is a Number, which is the byte index of the column
2244 position given with {expr}. The accepted positions are:
2245 . the cursor position
2246 $ the end of the cursor line (the result is the
2247 number of characters in the cursor line plus one)
2248 'x position of mark x (if the mark is not set, 0 is
2249 returned)
2250 Additionally {expr} can be [lnum, col]: a |List| with the line
2251 and column number. Most useful when the column is "$", to get
2252 the last column of a specific line. When "lnum" or "col" is
2253 out of range then col() returns zero.
2254 To get the line number use |line()|. To get both use
2255 |getpos()|.
2256 For the screen column position use |virtcol()|.
2257 Note that only marks in the current file can be used.
2258 Examples: >
2259 col(".") column of cursor
2260 col("$") length of cursor line plus one
2261 col("'t") column of mark t
2262 col("'" . markname) column of mark markname
2263 < The first column is 1. 0 is returned for an error.
2264 For an uppercase mark the column may actually be in another
2265 buffer.
2266 For the cursor position, when 'virtualedit' is active, the
2267 column is one higher if the cursor is after the end of the
2268 line. This can be used to obtain the column in Insert mode: >
2269 :imap <F2> <C-O>:let save_ve = &ve<CR>
2270 \<C-O>:set ve=all<CR>
2271 \<C-O>:echo col(".") . "\n" <Bar>
2272 \let &ve = save_ve<CR>
2273 <
2275 complete({startcol}, {matches}) *complete()* *E785*
2276 Set the matches for Insert mode completion.
2277 Can only be used in Insert mode. You need to use a mapping
2278 with CTRL-R = |i_CTRL-R|. It does not work after CTRL-O or
2279 with an expression mapping.
2280 {startcol} is the byte offset in the line where the completed
2281 text start. The text up to the cursor is the original text
2282 that will be replaced by the matches. Use col('.') for an
2283 empty string. "col('.') - 1" will replace one character by a
2284 match.
2285 {matches} must be a |List|. Each |List| item is one match.
2286 See |complete-items| for the kind of items that are possible.
2287 Note that the after calling this function you need to avoid
2288 inserting anything that would cause completion to stop.
2289 The match can be selected with CTRL-N and CTRL-P as usual with
2290 Insert mode completion. The popup menu will appear if
2291 specified, see |ins-completion-menu|.
2292 Example: >
2293 inoremap <F5> <C-R>=ListMonths()<CR>
2295 func! ListMonths()
2296 call complete(col('.'), ['January', 'February', 'March',
2297 \ 'April', 'May', 'June', 'July', 'August', 'September',
2298 \ 'October', 'November', 'December'])
2299 return ''
2300 endfunc
2301 < This isn't very useful, but it shows how it works. Note that
2302 an empty string is returned to avoid a zero being inserted.
2304 complete_add({expr}) *complete_add()*
2305 Add {expr} to the list of matches. Only to be used by the
2306 function specified with the 'completefunc' option.
2307 Returns 0 for failure (empty string or out of memory),
2308 1 when the match was added, 2 when the match was already in
2309 the list.
2310 See |complete-functions| for an explanation of {expr}. It is
2311 the same as one item in the list that 'omnifunc' would return.
2313 complete_check() *complete_check()*
2314 Check for a key typed while looking for completion matches.
2315 This is to be used when looking for matches takes some time.
2316 Returns non-zero when searching for matches is to be aborted,
2317 zero otherwise.
2318 Only to be used by the function specified with the
2319 'completefunc' option.
2321 *confirm()*
2322 confirm({msg} [, {choices} [, {default} [, {type}]]])
2323 Confirm() offers the user a dialog, from which a choice can be
2324 made. It returns the number of the choice. For the first
2325 choice this is 1.
2326 Note: confirm() is only supported when compiled with dialog
2327 support, see |+dialog_con| and |+dialog_gui|.
2328 {msg} is displayed in a |dialog| with {choices} as the
2329 alternatives. When {choices} is missing or empty, "&OK" is
2330 used (and translated).
2331 {msg} is a String, use '\n' to include a newline. Only on
2332 some systems the string is wrapped when it doesn't fit.
2333 {choices} is a String, with the individual choices separated
2334 by '\n', e.g. >
2335 confirm("Save changes?", "&Yes\n&No\n&Cancel")
2336 < The letter after the '&' is the shortcut key for that choice.
2337 Thus you can type 'c' to select "Cancel". The shortcut does
2338 not need to be the first letter: >
2339 confirm("file has been modified", "&Save\nSave &All")
2340 < For the console, the first letter of each choice is used as
2341 the default shortcut key.
2342 The optional {default} argument is the number of the choice
2343 that is made if the user hits <CR>. Use 1 to make the first
2344 choice the default one. Use 0 to not set a default. If
2345 {default} is omitted, 1 is used.
2346 The optional {type} argument gives the type of dialog. This
2347 is only used for the icon of the Win32 GUI. It can be one of
2348 these values: "Error", "Question", "Info", "Warning" or
2349 "Generic". Only the first character is relevant. When {type}
2350 is omitted, "Generic" is used.
2351 If the user aborts the dialog by pressing <Esc>, CTRL-C,
2352 or another valid interrupt key, confirm() returns 0.
2354 An example: >
2355 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2)
2356 :if choice == 0
2357 : echo "make up your mind!"
2358 :elseif choice == 3
2359 : echo "tasteful"
2360 :else
2361 : echo "I prefer bananas myself."
2362 :endif
2363 < In a GUI dialog, buttons are used. The layout of the buttons
2364 depends on the 'v' flag in 'guioptions'. If it is included,
2365 the buttons are always put vertically. Otherwise, confirm()
2366 tries to put the buttons in one horizontal line. If they
2367 don't fit, a vertical layout is used anyway. For some systems
2368 the horizontal layout is always used.
2370 *copy()*
2371 copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
2372 different from using {expr} directly.
2373 When {expr} is a |List| a shallow copy is created. This means
2374 that the original |List| can be changed without changing the
2375 copy, and vice versa. But the items are identical, thus
2376 changing an item changes the contents of both |Lists|. Also
2377 see |deepcopy()|.
2379 cos({expr}) *cos()*
2380 Return the cosine of {expr}, measured in radians, as a |Float|.
2381 {expr} must evaluate to a |Float| or a |Number|.
2382 Examples: >
2383 :echo cos(100)
2384 < 0.862319 >
2385 :echo cos(-4.01)
2386 < -0.646043
2387 {only available when compiled with the |+float| feature}
2390 cosh({expr}) *cosh()*
2391 Return the hyperbolic cosine of {expr} as a|Float|in [1,inf].
2392 {expr} must evaluate to a|Float|or a|Number|.
2393 Examples: >
2394 :echo cosh(0.5)
2395 < 1.127626 >
2396 :echo cosh(-0.5)
2397 < -1.127626
2398 {only available when compiled with|+float|and extention}
2401 count({comp}, {expr} [, {ic} [, {start}]]) *count()*
2402 Return the number of times an item with value {expr} appears
2403 in |List| or |Dictionary| {comp}.
2404 If {start} is given then start with the item with this index.
2405 {start} can only be used with a |List|.
2406 When {ic} is given and it's non-zero then case is ignored.
2409 *cscope_connection()*
2410 cscope_connection([{num} , {dbpath} [, {prepend}]])
2411 Checks for the existence of a |cscope| connection. If no
2412 parameters are specified, then the function returns:
2413 0, if cscope was not available (not compiled in), or
2414 if there are no cscope connections;
2415 1, if there is at least one cscope connection.
2417 If parameters are specified, then the value of {num}
2418 determines how existence of a cscope connection is checked:
2420 {num} Description of existence check
2421 ----- ------------------------------
2422 0 Same as no parameters (e.g., "cscope_connection()").
2423 1 Ignore {prepend}, and use partial string matches for
2424 {dbpath}.
2425 2 Ignore {prepend}, and use exact string matches for
2426 {dbpath}.
2427 3 Use {prepend}, use partial string matches for both
2428 {dbpath} and {prepend}.
2429 4 Use {prepend}, use exact string matches for both
2430 {dbpath} and {prepend}.
2432 Note: All string comparisons are case sensitive!
2434 Examples. Suppose we had the following (from ":cs show"): >
2436 # pid database name prepend path
2437 0 27664 cscope.out /usr/local
2438 <
2439 Invocation Return Val ~
2440 ---------- ---------- >
2441 cscope_connection() 1
2442 cscope_connection(1, "out") 1
2443 cscope_connection(2, "out") 0
2444 cscope_connection(3, "out") 0
2445 cscope_connection(3, "out", "local") 1
2446 cscope_connection(4, "out") 0
2447 cscope_connection(4, "out", "local") 0
2448 cscope_connection(4, "cscope.out", "/usr/local") 1
2449 <
2450 cursor({lnum}, {col} [, {off}]) *cursor()*
2451 cursor({list})
2452 Positions the cursor at the column (byte count) {col} in the
2453 line {lnum}. The first column is one.
2454 When there is one argument {list} this is used as a |List|
2455 with two or three items {lnum}, {col} and {off}. This is like
2456 the return value of |getpos()|, but without the first item.
2457 Does not change the jumplist.
2458 If {lnum} is greater than the number of lines in the buffer,
2459 the cursor will be positioned at the last line in the buffer.
2460 If {lnum} is zero, the cursor will stay in the current line.
2461 If {col} is greater than the number of bytes in the line,
2462 the cursor will be positioned at the last character in the
2463 line.
2464 If {col} is zero, the cursor will stay in the current column.
2465 When 'virtualedit' is used {off} specifies the offset in
2466 screen columns from the start of the character. E.g., a
2467 position within a <Tab> or after the last character.
2468 Returns 0 when the position could be set, -1 otherwise.
2471 deepcopy({expr}[, {noref}]) *deepcopy()* *E698*
2472 Make a copy of {expr}. For Numbers and Strings this isn't
2473 different from using {expr} directly.
2474 When {expr} is a |List| a full copy is created. This means
2475 that the original |List| can be changed without changing the
2476 copy, and vice versa. When an item is a |List|, a copy for it
2477 is made, recursively. Thus changing an item in the copy does
2478 not change the contents of the original |List|.
2479 When {noref} is omitted or zero a contained |List| or
2480 |Dictionary| is only copied once. All references point to
2481 this single copy. With {noref} set to 1 every occurrence of a
2482 |List| or |Dictionary| results in a new copy. This also means
2483 that a cyclic reference causes deepcopy() to fail.
2484 *E724*
2485 Nesting is possible up to 100 levels. When there is an item
2486 that refers back to a higher level making a deep copy with
2487 {noref} set to 1 will fail.
2488 Also see |copy()|.
2490 delete({fname}) *delete()*
2491 Deletes the file by the name {fname}. The result is a Number,
2492 which is 0 if the file was deleted successfully, and non-zero
2493 when the deletion failed.
2494 Use |remove()| to delete an item from a |List|.
2496 *did_filetype()*
2497 did_filetype() Returns non-zero when autocommands are being executed and the
2498 FileType event has been triggered at least once. Can be used
2499 to avoid triggering the FileType event again in the scripts
2500 that detect the file type. |FileType|
2501 When editing another file, the counter is reset, thus this
2502 really checks if the FileType event has been triggered for the
2503 current buffer. This allows an autocommand that starts
2504 editing another buffer to set 'filetype' and load a syntax
2505 file.
2507 diff_filler({lnum}) *diff_filler()*
2508 Returns the number of filler lines above line {lnum}.
2509 These are the lines that were inserted at this point in
2510 another diff'ed window. These filler lines are shown in the
2511 display but don't exist in the buffer.
2512 {lnum} is used like with |getline()|. Thus "." is the current
2513 line, "'m" mark m, etc.
2514 Returns 0 if the current window is not in diff mode.
2516 diff_hlID({lnum}, {col}) *diff_hlID()*
2517 Returns the highlight ID for diff mode at line {lnum} column
2518 {col} (byte index). When the current line does not have a
2519 diff change zero is returned.
2520 {lnum} is used like with |getline()|. Thus "." is the current
2521 line, "'m" mark m, etc.
2522 {col} is 1 for the leftmost column, {lnum} is 1 for the first
2523 line.
2524 The highlight ID can be used with |synIDattr()| to obtain
2525 syntax information about the highlighting.
2527 empty({expr}) *empty()*
2528 Return the Number 1 if {expr} is empty, zero otherwise.
2529 A |List| or |Dictionary| is empty when it does not have any
2530 items. A Number is empty when its value is zero.
2531 For a long |List| this is much faster than comparing the
2532 length with zero.
2534 escape({string}, {chars}) *escape()*
2535 Escape the characters in {chars} that occur in {string} with a
2536 backslash. Example: >
2537 :echo escape('c:\program files\vim', ' \')
2538 < results in: >
2539 c:\\program\ files\\vim
2540 < Also see |shellescape()|.
2542 *eval()*
2543 eval({string}) Evaluate {string} and return the result. Especially useful to
2544 turn the result of |string()| back into the original value.
2545 This works for Numbers, Floats, Strings and composites of
2546 them. Also works for |Funcref|s that refer to existing
2547 functions.
2549 eventhandler() *eventhandler()*
2550 Returns 1 when inside an event handler. That is that Vim got
2551 interrupted while waiting for the user to type a character,
2552 e.g., when dropping a file on Vim. This means interactive
2553 commands cannot be used. Otherwise zero is returned.
2555 executable({expr}) *executable()*
2556 This function checks if an executable with the name {expr}
2557 exists. {expr} must be the name of the program without any
2558 arguments.
2559 executable() uses the value of $PATH and/or the normal
2560 searchpath for programs. *PATHEXT*
2561 On MS-DOS and MS-Windows the ".exe", ".bat", etc. can
2562 optionally be included. Then the extensions in $PATHEXT are
2563 tried. Thus if "foo.exe" does not exist, "foo.exe.bat" can be
2564 found. If $PATHEXT is not set then ".exe;.com;.bat;.cmd" is
2565 used. A dot by itself can be used in $PATHEXT to try using
2566 the name without an extension. When 'shell' looks like a
2567 Unix shell, then the name is also tried without adding an
2568 extension.
2569 On MS-DOS and MS-Windows it only checks if the file exists and
2570 is not a directory, not if it's really executable.
2571 On MS-Windows an executable in the same directory as Vim is
2572 always found. Since this directory is added to $PATH it
2573 should also work to execute it |win32-PATH|.
2574 The result is a Number:
2575 1 exists
2576 0 does not exist
2577 -1 not implemented on this system
2579 *exists()*
2580 exists({expr}) The result is a Number, which is non-zero if {expr} is
2581 defined, zero otherwise. The {expr} argument is a string,
2582 which contains one of these:
2583 &option-name Vim option (only checks if it exists,
2584 not if it really works)
2585 +option-name Vim option that works.
2586 $ENVNAME environment variable (could also be
2587 done by comparing with an empty
2588 string)
2589 *funcname built-in function (see |functions|)
2590 or user defined function (see
2591 |user-functions|).
2592 varname internal variable (see
2593 |internal-variables|). Also works
2594 for |curly-braces-names|, |Dictionary|
2595 entries, |List| items, etc. Beware
2596 that evaluating an index may cause an
2597 error message for an invalid
2598 expression. E.g.: >
2599 :let l = [1, 2, 3]
2600 :echo exists("l[5]")
2601 < 0 >
2602 :echo exists("l[xx]")
2603 < E121: Undefined variable: xx
2604 0
2605 :cmdname Ex command: built-in command, user
2606 command or command modifier |:command|.
2607 Returns:
2608 1 for match with start of a command
2609 2 full match with a command
2610 3 matches several user commands
2611 To check for a supported command
2612 always check the return value to be 2.
2613 :2match The |:2match| command.
2614 :3match The |:3match| command.
2615 #event autocommand defined for this event
2616 #event#pattern autocommand defined for this event and
2617 pattern (the pattern is taken
2618 literally and compared to the
2619 autocommand patterns character by
2620 character)
2621 #group autocommand group exists
2622 #group#event autocommand defined for this group and
2623 event.
2624 #group#event#pattern
2625 autocommand defined for this group,
2626 event and pattern.
2627 ##event autocommand for this event is
2628 supported.
2629 For checking for a supported feature use |has()|.
2631 Examples: >
2632 exists("&shortname")
2633 exists("$HOSTNAME")
2634 exists("*strftime")
2635 exists("*s:MyFunc")
2636 exists("bufcount")
2637 exists(":Make")
2638 exists("#CursorHold")
2639 exists("#BufReadPre#*.gz")
2640 exists("#filetypeindent")
2641 exists("#filetypeindent#FileType")
2642 exists("#filetypeindent#FileType#*")
2643 exists("##ColorScheme")
2644 < There must be no space between the symbol (&/$/*/#) and the
2645 name.
2646 There must be no extra characters after the name, although in
2647 a few cases this is ignored. That may become more strict in
2648 the future, thus don't count on it!
2649 Working example: >
2650 exists(":make")
2651 < NOT working example: >
2652 exists(":make install")
2654 < Note that the argument must be a string, not the name of the
2655 variable itself. For example: >
2656 exists(bufcount)
2657 < This doesn't check for existence of the "bufcount" variable,
2658 but gets the value of "bufcount", and checks if that exists.
2660 exp({expr}) *exp()*
2661 Return the exponential of {expr} as a|Float|in [0,inf].
2662 {expr} must evaluate to a|Float|or a|Number|.
2663 Examples: >
2664 :echo exp(2)
2665 < 7.389056 >
2666 :echo exp(-1)
2667 < 0.367879
2668 {only available when compiled with|+float|and extention}
2670 expand({expr} [, {flag}]) *expand()*
2671 Expand wildcards and the following special keywords in {expr}.
2672 The result is a String.
2674 When there are several matches, they are separated by <NL>
2675 characters. [Note: in version 5.0 a space was used, which
2676 caused problems when a file name contains a space]
2678 If the expansion fails, the result is an empty string. A name
2679 for a non-existing file is not included.
2681 When {expr} starts with '%', '#' or '<', the expansion is done
2682 like for the |cmdline-special| variables with their associated
2683 modifiers. Here is a short overview:
2685 % current file name
2686 # alternate file name
2687 #n alternate file name n
2688 <cfile> file name under the cursor
2689 <afile> autocmd file name
2690 <abuf> autocmd buffer number (as a String!)
2691 <amatch> autocmd matched name
2692 <sfile> sourced script file name
2693 <cword> word under the cursor
2694 <cWORD> WORD under the cursor
2695 <client> the {clientid} of the last received
2696 message |server2client()|
2697 Modifiers:
2698 :p expand to full path
2699 :h head (last path component removed)
2700 :t tail (last path component only)
2701 :r root (one extension removed)
2702 :e extension only
2704 Example: >
2705 :let &tags = expand("%:p:h") . "/tags"
2706 < Note that when expanding a string that starts with '%', '#' or
2707 '<', any following text is ignored. This does NOT work: >
2708 :let doesntwork = expand("%:h.bak")
2709 < Use this: >
2710 :let doeswork = expand("%:h") . ".bak"
2711 < Also note that expanding "<cfile>" and others only returns the
2712 referenced file name without further expansion. If "<cfile>"
2713 is "~/.cshrc", you need to do another expand() to have the
2714 "~/" expanded into the path of the home directory: >
2715 :echo expand(expand("<cfile>"))
2716 <
2717 There cannot be white space between the variables and the
2718 following modifier. The |fnamemodify()| function can be used
2719 to modify normal file names.
2721 When using '%' or '#', and the current or alternate file name
2722 is not defined, an empty string is used. Using "%:p" in a
2723 buffer with no name, results in the current directory, with a
2724 '/' added.
2726 When {expr} does not start with '%', '#' or '<', it is
2727 expanded like a file name is expanded on the command line.
2728 'suffixes' and 'wildignore' are used, unless the optional
2729 {flag} argument is given and it is non-zero. Names for
2730 non-existing files are included. The "**" item can be used to
2731 search in a directory tree. For example, to find all "README"
2732 files in the current directory and below: >
2733 :echo expand("**/README")
2734 <
2735 Expand() can also be used to expand variables and environment
2736 variables that are only known in a shell. But this can be
2737 slow, because a shell must be started. See |expr-env-expand|.
2738 The expanded variable is still handled like a list of file
2739 names. When an environment variable cannot be expanded, it is
2740 left unchanged. Thus ":echo expand('$FOOBAR')" results in
2741 "$FOOBAR".
2743 See |glob()| for finding existing files. See |system()| for
2744 getting the raw output of an external command.
2746 extend({expr1}, {expr2} [, {expr3}]) *extend()*
2747 {expr1} and {expr2} must be both |Lists| or both
2748 |Dictionaries|.
2750 If they are |Lists|: Append {expr2} to {expr1}.
2751 If {expr3} is given insert the items of {expr2} before item
2752 {expr3} in {expr1}. When {expr3} is zero insert before the
2753 first item. When {expr3} is equal to len({expr1}) then
2754 {expr2} is appended.
2755 Examples: >
2756 :echo sort(extend(mylist, [7, 5]))
2757 :call extend(mylist, [2, 3], 1)
2758 < When {expr1} is the same List as {expr2} then the number of
2759 items copied is equal to the original length of the List.
2760 E.g., when {expr3} is 1 you get N new copies of the first item
2761 (where N is the original length of the List).
2762 Use |add()| to concatenate one item to a list. To concatenate
2763 two lists into a new list use the + operator: >
2764 :let newlist = [1, 2, 3] + [4, 5]
2765 <
2766 If they are |Dictionaries|:
2767 Add all entries from {expr2} to {expr1}.
2768 If a key exists in both {expr1} and {expr2} then {expr3} is
2769 used to decide what to do:
2770 {expr3} = "keep": keep the value of {expr1}
2771 {expr3} = "force": use the value of {expr2}
2772 {expr3} = "error": give an error message *E737*
2773 When {expr3} is omitted then "force" is assumed.
2775 {expr1} is changed when {expr2} is not empty. If necessary
2776 make a copy of {expr1} first.
2777 {expr2} remains unchanged.
2778 Returns {expr1}.
2781 feedkeys({string} [, {mode}]) *feedkeys()*
2782 Characters in {string} are queued for processing as if they
2783 come from a mapping or were typed by the user. They are added
2784 to the end of the typeahead buffer, thus if a mapping is still
2785 being executed these characters come after them.
2786 The function does not wait for processing of keys contained in
2787 {string}.
2788 To include special keys into {string}, use double-quotes
2789 and "\..." notation |expr-quote|. For example,
2790 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
2791 feedkeys('\<CR>') pushes 5 characters.
2792 If {mode} is absent, keys are remapped.
2793 {mode} is a String, which can contain these character flags:
2794 'm' Remap keys. This is default.
2795 'n' Do not remap keys.
2796 't' Handle keys as if typed; otherwise they are handled as
2797 if coming from a mapping. This matters for undo,
2798 opening folds, etc.
2799 Return value is always 0.
2801 filereadable({file}) *filereadable()*
2802 The result is a Number, which is TRUE when a file with the
2803 name {file} exists, and can be read. If {file} doesn't exist,
2804 or is a directory, the result is FALSE. {file} is any
2805 expression, which is used as a String.
2806 If you don't care about the file being readable you can use
2807 |glob()|.
2808 *file_readable()*
2809 Obsolete name: file_readable().
2812 filewritable({file}) *filewritable()*
2813 The result is a Number, which is 1 when a file with the
2814 name {file} exists, and can be written. If {file} doesn't
2815 exist, or is not writable, the result is 0. If {file} is a
2816 directory, and we can write to it, the result is 2.
2819 filter({expr}, {string}) *filter()*
2820 {expr} must be a |List| or a |Dictionary|.
2821 For each item in {expr} evaluate {string} and when the result
2822 is zero remove the item from the |List| or |Dictionary|.
2823 Inside {string} |v:val| has the value of the current item.
2824 For a |Dictionary| |v:key| has the key of the current item.
2825 Examples: >
2826 :call filter(mylist, 'v:val !~ "OLD"')
2827 < Removes the items where "OLD" appears. >
2828 :call filter(mydict, 'v:key >= 8')
2829 < Removes the items with a key below 8. >
2830 :call filter(var, 0)
2831 < Removes all the items, thus clears the |List| or |Dictionary|.
2833 Note that {string} is the result of expression and is then
2834 used as an expression again. Often it is good to use a
2835 |literal-string| to avoid having to double backslashes.
2837 The operation is done in-place. If you want a |List| or
2838 |Dictionary| to remain unmodified make a copy first: >
2839 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
2841 < Returns {expr}, the |List| or |Dictionary| that was filtered.
2842 When an error is encountered while evaluating {string} no
2843 further items in {expr} are processed.
2846 finddir({name}[, {path}[, {count}]]) *finddir()*
2847 Find directory {name} in {path}. Supports both downwards and
2848 upwards recursive directory searches. See |file-searching|
2849 for the syntax of {path}.
2850 Returns the path of the first found match. When the found
2851 directory is below the current directory a relative path is
2852 returned. Otherwise a full path is returned.
2853 If {path} is omitted or empty then 'path' is used.
2854 If the optional {count} is given, find {count}'s occurrence of
2855 {name} in {path} instead of the first one.
2856 When {count} is negative return all the matches in a |List|.
2857 This is quite similar to the ex-command |:find|.
2858 {only available when compiled with the +file_in_path feature}
2860 findfile({name}[, {path}[, {count}]]) *findfile()*
2861 Just like |finddir()|, but find a file instead of a directory.
2862 Uses 'suffixesadd'.
2863 Example: >
2864 :echo findfile("tags.vim", ".;")
2865 < Searches from the directory of the current file upwards until
2866 it finds the file "tags.vim".
2868 float2nr({expr}) *float2nr()*
2869 Convert {expr} to a Number by omitting the part after the
2870 decimal point.
2871 {expr} must evaluate to a |Float| or a Number.
2872 When the value of {expr} is out of range for a |Number| the
2873 result is truncated to 0x7fffffff or -0x7fffffff. NaN results
2874 in -0x80000000.
2875 Examples: >
2876 echo float2nr(3.95)
2877 < 3 >
2878 echo float2nr(-23.45)
2879 < -23 >
2880 echo float2nr(1.0e100)
2881 < 2147483647 >
2882 echo float2nr(-1.0e150)
2883 < -2147483647 >
2884 echo float2nr(1.0e-100)
2885 < 0
2886 {only available when compiled with the |+float| feature}
2889 floor({expr}) *floor()*
2890 Return the largest integral value less than or equal to
2891 {expr} as a |Float| (round down).
2892 {expr} must evaluate to a |Float| or a |Number|.
2893 Examples: >
2894 echo floor(1.856)
2895 < 1.0 >
2896 echo floor(-5.456)
2897 < -6.0 >
2898 echo floor(4.0)
2899 < 4.0
2900 {only available when compiled with the |+float| feature}
2902 fmod({expr1},{expr2}) *fmod()*
2903 Return the remainder of {expr1}/{expr2}, even if the division
2904 is not representable. Returns {expr1} - i * {expr2} for some
2905 integer i such that if {expr2} is non-zero, the result has the
2906 same sign as {expr1} and magnitude less than the magnitude of
2907 {expr2}. If {expr2} is zero, the value returned is zero. The
2908 value returned is a|Float|.
2909 {expr1} and {expr2} must evaluate to a|Float|or a|Number|.
2910 Examples: >
2911 :echo fmod(12.33,1.22)
2912 < 0.13 >
2913 :echo fmod(-12.33,1.22)
2914 < -0.13
2915 {only available when compiled with|+float|and extention}
2917 fnameescape({string}) *fnameescape()*
2918 Escape {string} for use as file name command argument. All
2919 characters that have a special meaning, such as '%' and '|'
2920 are escaped with a backslash.
2921 For most systems the characters escaped are
2922 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
2923 appears in a filename, it depends on the value of 'isfname'.
2924 A leading '+' and '>' is also escaped (special after |:edit|
2925 and |:write|). And a "-" by itself (special after |:cd|).
2926 Example: >
2927 :let fname = '+some str%nge|name'
2928 :exe "edit " . fnameescape(fname)
2929 < results in executing: >
2930 edit \+some\ str\%nge\|name
2932 fnamemodify({fname}, {mods}) *fnamemodify()*
2933 Modify file name {fname} according to {mods}. {mods} is a
2934 string of characters like it is used for file names on the
2935 command line. See |filename-modifiers|.
2936 Example: >
2937 :echo fnamemodify("main.c", ":p:h")
2938 < results in: >
2939 /home/mool/vim/vim/src
2940 < Note: Environment variables don't work in {fname}, use
2941 |expand()| first then.
2943 foldclosed({lnum}) *foldclosed()*
2944 The result is a Number. If the line {lnum} is in a closed
2945 fold, the result is the number of the first line in that fold.
2946 If the line {lnum} is not in a closed fold, -1 is returned.
2948 foldclosedend({lnum}) *foldclosedend()*
2949 The result is a Number. If the line {lnum} is in a closed
2950 fold, the result is the number of the last line in that fold.
2951 If the line {lnum} is not in a closed fold, -1 is returned.
2953 foldlevel({lnum}) *foldlevel()*
2954 The result is a Number, which is the foldlevel of line {lnum}
2955 in the current buffer. For nested folds the deepest level is
2956 returned. If there is no fold at line {lnum}, zero is
2957 returned. It doesn't matter if the folds are open or closed.
2958 When used while updating folds (from 'foldexpr') -1 is
2959 returned for lines where folds are still to be updated and the
2960 foldlevel is unknown. As a special case the level of the
2961 previous line is usually available.
2963 *foldtext()*
2964 foldtext() Returns a String, to be displayed for a closed fold. This is
2965 the default function used for the 'foldtext' option and should
2966 only be called from evaluating 'foldtext'. It uses the
2967 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
2968 The returned string looks like this: >
2969 +-- 45 lines: abcdef
2970 < The number of dashes depends on the foldlevel. The "45" is
2971 the number of lines in the fold. "abcdef" is the text in the
2972 first non-blank line of the fold. Leading white space, "//"
2973 or "/*" and the text from the 'foldmarker' and 'commentstring'
2974 options is removed.
2975 {not available when compiled without the |+folding| feature}
2977 foldtextresult({lnum}) *foldtextresult()*
2978 Returns the text that is displayed for the closed fold at line
2979 {lnum}. Evaluates 'foldtext' in the appropriate context.
2980 When there is no closed fold at {lnum} an empty string is
2981 returned.
2982 {lnum} is used like with |getline()|. Thus "." is the current
2983 line, "'m" mark m, etc.
2984 Useful when exporting folded text, e.g., to HTML.
2985 {not available when compiled without the |+folding| feature}
2987 *foreground()*
2988 foreground() Move the Vim window to the foreground. Useful when sent from
2989 a client to a Vim server. |remote_send()|
2990 On Win32 systems this might not work, the OS does not always
2991 allow a window to bring itself to the foreground. Use
2992 |remote_foreground()| instead.
2993 {only in the Win32, Athena, Motif and GTK GUI versions and the
2994 Win32 console version}
2997 function({name}) *function()* *E700*
2998 Return a |Funcref| variable that refers to function {name}.
2999 {name} can be a user defined function or an internal function.
3002 garbagecollect([at_exit]) *garbagecollect()*
3003 Cleanup unused |Lists| and |Dictionaries| that have circular
3004 references. There is hardly ever a need to invoke this
3005 function, as it is automatically done when Vim runs out of
3006 memory or is waiting for the user to press a key after
3007 'updatetime'. Items without circular references are always
3008 freed when they become unused.
3009 This is useful if you have deleted a very big |List| and/or
3010 |Dictionary| with circular references in a script that runs
3011 for a long time.
3012 When the optional "at_exit" argument is one, garbage
3013 collection will also be done when exiting Vim, if it wasn't
3014 done before. This is useful when checking for memory leaks.
3016 get({list}, {idx} [, {default}]) *get()*
3017 Get item {idx} from |List| {list}. When this item is not
3018 available return {default}. Return zero when {default} is
3019 omitted.
3020 get({dict}, {key} [, {default}])
3021 Get item with key {key} from |Dictionary| {dict}. When this
3022 item is not available return {default}. Return zero when
3023 {default} is omitted.
3025 *getbufline()*
3026 getbufline({expr}, {lnum} [, {end}])
3027 Return a |List| with the lines starting from {lnum} to {end}
3028 (inclusive) in the buffer {expr}. If {end} is omitted, a
3029 |List| with only the line {lnum} is returned.
3031 For the use of {expr}, see |bufname()| above.
3033 For {lnum} and {end} "$" can be used for the last line of the
3034 buffer. Otherwise a number must be used.
3036 When {lnum} is smaller than 1 or bigger than the number of
3037 lines in the buffer, an empty |List| is returned.
3039 When {end} is greater than the number of lines in the buffer,
3040 it is treated as {end} is set to the number of lines in the
3041 buffer. When {end} is before {lnum} an empty |List| is
3042 returned.
3044 This function works only for loaded buffers. For unloaded and
3045 non-existing buffers, an empty |List| is returned.
3047 Example: >
3048 :let lines = getbufline(bufnr("myfile"), 1, "$")
3050 getbufvar({expr}, {varname}) *getbufvar()*
3051 The result is the value of option or local buffer variable
3052 {varname} in buffer {expr}. Note that the name without "b:"
3053 must be used.
3054 When {varname} is empty returns a dictionary with all the
3055 buffer-local variables.
3056 This also works for a global or buffer-local option, but it
3057 doesn't work for a global variable, window-local variable or
3058 window-local option.
3059 For the use of {expr}, see |bufname()| above.
3060 When the buffer or variable doesn't exist an empty string is
3061 returned, there is no error message.
3062 Examples: >
3063 :let bufmodified = getbufvar(1, "&mod")
3064 :echo "todo myvar = " . getbufvar("todo", "myvar")
3065 <
3066 getchar([expr]) *getchar()*
3067 Get a single character from the user or input stream.
3068 If [expr] is omitted, wait until a character is available.
3069 If [expr] is 0, only get a character when one is available.
3070 Return zero otherwise.
3071 If [expr] is 1, only check if a character is available, it is
3072 not consumed. Return zero if no character available.
3074 Without {expr} and when {expr} is 0 a whole character or
3075 special key is returned. If it is an 8-bit character, the
3076 result is a number. Use nr2char() to convert it to a String.
3077 Otherwise a String is returned with the encoded character.
3078 For a special key it's a sequence of bytes starting with 0x80
3079 (decimal: 128). This is the same value as the string
3080 "\<Key>", e.g., "\<Left>". The returned value is also a
3081 String when a modifier (shift, control, alt) was used that is
3082 not included in the character.
3084 When {expr} is 1 only the first byte is returned. For a
3085 one-byte character it is the character itself as a number.
3086 Use nr2char() to convert it to a String.
3088 When the user clicks a mouse button, the mouse event will be
3089 returned. The position can then be found in |v:mouse_col|,
3090 |v:mouse_lnum| and |v:mouse_win|. This example positions the
3091 mouse as it would normally happen: >
3092 let c = getchar()
3093 if c == "\<LeftMouse>" && v:mouse_win > 0
3094 exe v:mouse_win . "wincmd w"
3095 exe v:mouse_lnum
3096 exe "normal " . v:mouse_col . "|"
3097 endif
3098 <
3099 There is no prompt, you will somehow have to make clear to the
3100 user that a character has to be typed.
3101 There is no mapping for the character.
3102 Key codes are replaced, thus when the user presses the <Del>
3103 key you get the code for the <Del> key, not the raw character
3104 sequence. Examples: >
3105 getchar() == "\<Del>"
3106 getchar() == "\<S-Left>"
3107 < This example redefines "f" to ignore case: >
3108 :nmap f :call FindChar()<CR>
3109 :function FindChar()
3110 : let c = nr2char(getchar())
3111 : while col('.') < col('$') - 1
3112 : normal l
3113 : if getline('.')[col('.') - 1] ==? c
3114 : break
3115 : endif
3116 : endwhile
3117 :endfunction
3119 getcharmod() *getcharmod()*
3120 The result is a Number which is the state of the modifiers for
3121 the last obtained character with getchar() or in another way.
3122 These values are added together:
3123 2 shift
3124 4 control
3125 8 alt (meta)
3126 16 mouse double click
3127 32 mouse triple click
3128 64 mouse quadruple click
3129 128 Macintosh only: command
3130 Only the modifiers that have not been included in the
3131 character itself are obtained. Thus Shift-a results in "A"
3132 without a modifier.
3134 getcmdline() *getcmdline()*
3135 Return the current command-line. Only works when the command
3136 line is being edited, thus requires use of |c_CTRL-\_e| or
3137 |c_CTRL-R_=|.
3138 Example: >
3139 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
3140 < Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
3142 getcmdpos() *getcmdpos()*
3143 Return the position of the cursor in the command line as a
3144 byte count. The first column is 1.
3145 Only works when editing the command line, thus requires use of
3146 |c_CTRL-\_e| or |c_CTRL-R_=|. Returns 0 otherwise.
3147 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
3149 getcmdtype() *getcmdtype()*
3150 Return the current command-line type. Possible return values
3151 are:
3152 : normal Ex command
3153 > debug mode command |debug-mode|
3154 / forward search command
3155 ? backward search command
3156 @ |input()| command
3157 - |:insert| or |:append| command
3158 Only works when editing the command line, thus requires use of
3159 |c_CTRL-\_e| or |c_CTRL-R_=|. Returns an empty string
3160 otherwise.
3161 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
3163 *getcwd()*
3164 getcwd() The result is a String, which is the name of the current
3165 working directory.
3167 getfsize({fname}) *getfsize()*
3168 The result is a Number, which is the size in bytes of the
3169 given file {fname}.
3170 If {fname} is a directory, 0 is returned.
3171 If the file {fname} can't be found, -1 is returned.
3172 If the size of {fname} is too big to fit in a Number then -2
3173 is returned.
3175 getfontname([{name}]) *getfontname()*
3176 Without an argument returns the name of the normal font being
3177 used. Like what is used for the Normal highlight group
3178 |hl-Normal|.
3179 With an argument a check is done whether {name} is a valid
3180 font name. If not then an empty string is returned.
3181 Otherwise the actual font name is returned, or {name} if the
3182 GUI does not support obtaining the real name.
3183 Only works when the GUI is running, thus not in your vimrc or
3184 gvimrc file. Use the |GUIEnter| autocommand to use this
3185 function just after the GUI has started.
3186 Note that the GTK 2 GUI accepts any font name, thus checking
3187 for a valid name does not work.
3189 getfperm({fname}) *getfperm()*
3190 The result is a String, which is the read, write, and execute
3191 permissions of the given file {fname}.
3192 If {fname} does not exist or its directory cannot be read, an
3193 empty string is returned.
3194 The result is of the form "rwxrwxrwx", where each group of
3195 "rwx" flags represent, in turn, the permissions of the owner
3196 of the file, the group the file belongs to, and other users.
3197 If a user does not have a given permission the flag for this
3198 is replaced with the string "-". Example: >
3199 :echo getfperm("/etc/passwd")
3200 < This will hopefully (from a security point of view) display
3201 the string "rw-r--r--" or even "rw-------".
3203 getftime({fname}) *getftime()*
3204 The result is a Number, which is the last modification time of
3205 the given file {fname}. The value is measured as seconds
3206 since 1st Jan 1970, and may be passed to strftime(). See also
3207 |localtime()| and |strftime()|.
3208 If the file {fname} can't be found -1 is returned.
3210 getftype({fname}) *getftype()*
3211 The result is a String, which is a description of the kind of
3212 file of the given file {fname}.
3213 If {fname} does not exist an empty string is returned.
3214 Here is a table over different kinds of files and their
3215 results:
3216 Normal file "file"
3217 Directory "dir"
3218 Symbolic link "link"
3219 Block device "bdev"
3220 Character device "cdev"
3221 Socket "socket"
3222 FIFO "fifo"
3223 All other "other"
3224 Example: >
3225 getftype("/home")
3226 < Note that a type such as "link" will only be returned on
3227 systems that support it. On some systems only "dir" and
3228 "file" are returned.
3230 *getline()*
3231 getline({lnum} [, {end}])
3232 Without {end} the result is a String, which is line {lnum}
3233 from the current buffer. Example: >
3234 getline(1)
3235 < When {lnum} is a String that doesn't start with a
3236 digit, line() is called to translate the String into a Number.
3237 To get the line under the cursor: >
3238 getline(".")
3239 < When {lnum} is smaller than 1 or bigger than the number of
3240 lines in the buffer, an empty string is returned.
3242 When {end} is given the result is a |List| where each item is
3243 a line from the current buffer in the range {lnum} to {end},
3244 including line {end}.
3245 {end} is used in the same way as {lnum}.
3246 Non-existing lines are silently omitted.
3247 When {end} is before {lnum} an empty |List| is returned.
3248 Example: >
3249 :let start = line('.')
3250 :let end = search("^$") - 1
3251 :let lines = getline(start, end)
3253 < To get lines from another buffer see |getbufline()|
3255 getloclist({nr}) *getloclist()*
3256 Returns a list with all the entries in the location list for
3257 window {nr}. When {nr} is zero the current window is used.
3258 For a location list window, the displayed location list is
3259 returned. For an invalid window number {nr}, an empty list is
3260 returned. Otherwise, same as |getqflist()|.
3262 getmatches() *getmatches()*
3263 Returns a |List| with all matches previously defined by
3264 |matchadd()| and the |:match| commands. |getmatches()| is
3265 useful in combination with |setmatches()|, as |setmatches()|
3266 can restore a list of matches saved by |getmatches()|.
3267 Example: >
3268 :echo getmatches()
3269 < [{'group': 'MyGroup1', 'pattern': 'TODO',
3270 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3271 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3272 :let m = getmatches()
3273 :call clearmatches()
3274 :echo getmatches()
3275 < [] >
3276 :call setmatches(m)
3277 :echo getmatches()
3278 < [{'group': 'MyGroup1', 'pattern': 'TODO',
3279 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
3280 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
3281 :unlet m
3282 <
3284 getqflist() *getqflist()*
3285 Returns a list with all the current quickfix errors. Each
3286 list item is a dictionary with these entries:
3287 bufnr number of buffer that has the file name, use
3288 bufname() to get the name
3289 lnum line number in the buffer (first line is 1)
3290 col column number (first column is 1)
3291 vcol non-zero: "col" is visual column
3292 zero: "col" is byte index
3293 nr error number
3294 pattern search pattern used to locate the error
3295 text description of the error
3296 type type of the error, 'E', '1', etc.
3297 valid non-zero: recognized error message
3299 When there is no error list or it's empty an empty list is
3300 returned. Quickfix list entries with non-existing buffer
3301 number are returned with "bufnr" set to zero.
3303 Useful application: Find pattern matches in multiple files and
3304 do something with them: >
3305 :vimgrep /theword/jg *.c
3306 :for d in getqflist()
3307 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
3308 :endfor
3311 getreg([{regname} [, 1]]) *getreg()*
3312 The result is a String, which is the contents of register
3313 {regname}. Example: >
3314 :let cliptext = getreg('*')
3315 < getreg('=') returns the last evaluated value of the expression
3316 register. (For use in maps.)
3317 getreg('=', 1) returns the expression itself, so that it can
3318 be restored with |setreg()|. For other registers the extra
3319 argument is ignored, thus you can always give it.
3320 If {regname} is not specified, |v:register| is used.
3323 getregtype([{regname}]) *getregtype()*
3324 The result is a String, which is type of register {regname}.
3325 The value will be one of:
3326 "v" for |characterwise| text
3327 "V" for |linewise| text
3328 "<CTRL-V>{width}" for |blockwise-visual| text
3329 0 for an empty or unknown register
3330 <CTRL-V> is one character with value 0x16.
3331 If {regname} is not specified, |v:register| is used.
3333 gettabwinvar({tabnr}, {winnr}, {varname}) *gettabwinvar()*
3334 Get the value of window-local variable {varname} in window
3335 {winnr} in tab page {tabnr}.
3336 When {varname} starts with "&" get the value of a window-local
3337 option.
3338 Tabs are numbered starting with one. For the current tabpage
3339 use |getwinvar()|.
3340 When {winnr} is zero the current window is used.
3341 This also works for a global option, buffer-local option and
3342 window-local option, but it doesn't work for a global variable
3343 or buffer-local variable.
3344 When {varname} is empty a dictionary with all window-local
3345 variables is returned.
3346 Note that {varname} must be the name without "w:".
3347 Examples: >
3348 :let list_is_on = gettabwinvar(1, 2, '&list')
3349 :echo "myvar = " . gettabwinvar(3, 1, 'myvar')
3350 <
3351 *getwinposx()*
3352 getwinposx() The result is a Number, which is the X coordinate in pixels of
3353 the left hand side of the GUI Vim window. The result will be
3354 -1 if the information is not available.
3356 *getwinposy()*
3357 getwinposy() The result is a Number, which is the Y coordinate in pixels of
3358 the top of the GUI Vim window. The result will be -1 if the
3359 information is not available.
3361 getwinvar({winnr}, {varname}) *getwinvar()*
3362 Like |gettabwinvar()| for the current tabpage.
3363 Examples: >
3364 :let list_is_on = getwinvar(2, '&list')
3365 :echo "myvar = " . getwinvar(1, 'myvar')
3366 <
3367 glob({expr} [, {flag}]) *glob()*
3368 Expand the file wildcards in {expr}. See |wildcards| for the
3369 use of special characters.
3370 The result is a String.
3371 When there are several matches, they are separated by <NL>
3372 characters.
3373 Unless the optional {flag} argument is given and is non-zero,
3374 the 'suffixes' and 'wildignore' options apply: Names matching
3375 one of the patterns in 'wildignore' will be skipped and
3376 'suffixes' affect the ordering of matches.
3377 If the expansion fails, the result is an empty string.
3378 A name for a non-existing file is not included.
3380 For most systems backticks can be used to get files names from
3381 any external command. Example: >
3382 :let tagfiles = glob("`find . -name tags -print`")
3383 :let &tags = substitute(tagfiles, "\n", ",", "g")
3384 < The result of the program inside the backticks should be one
3385 item per line. Spaces inside an item are allowed.
3387 See |expand()| for expanding special Vim variables. See
3388 |system()| for getting the raw output of an external command.
3390 globpath({path}, {expr} [, {flag}]) *globpath()*
3391 Perform glob() on all directories in {path} and concatenate
3392 the results. Example: >
3393 :echo globpath(&rtp, "syntax/c.vim")
3394 < {path} is a comma-separated list of directory names. Each
3395 directory name is prepended to {expr} and expanded like with
3396 |glob()|. A path separator is inserted when needed.
3397 To add a comma inside a directory name escape it with a
3398 backslash. Note that on MS-Windows a directory may have a
3399 trailing backslash, remove it if you put a comma after it.
3400 If the expansion fails for one of the directories, there is no
3401 error message.
3402 Unless the optional {flag} argument is given and is non-zero,
3403 the 'suffixes' and 'wildignore' options apply: Names matching
3404 one of the patterns in 'wildignore' will be skipped and
3405 'suffixes' affect the ordering of matches.
3407 The "**" item can be used to search in a directory tree.
3408 For example, to find all "README.txt" files in the directories
3409 in 'runtimepath' and below: >
3410 :echo globpath(&rtp, "**/README.txt")
3411 < Upwards search and limiting the depth of "**" is not
3412 supported, thus using 'path' will not always work properly.
3414 *has()*
3415 has({feature}) The result is a Number, which is 1 if the feature {feature} is
3416 supported, zero otherwise. The {feature} argument is a
3417 string. See |feature-list| below.
3418 Also see |exists()|.
3421 has_key({dict}, {key}) *has_key()*
3422 The result is a Number, which is 1 if |Dictionary| {dict} has
3423 an entry with key {key}. Zero otherwise.
3425 haslocaldir() *haslocaldir()*
3426 The result is a Number, which is 1 when the current
3427 window has set a local path via |:lcd|, and 0 otherwise.
3429 hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
3430 The result is a Number, which is 1 if there is a mapping that
3431 contains {what} in somewhere in the rhs (what it is mapped to)
3432 and this mapping exists in one of the modes indicated by
3433 {mode}.
3434 When {abbr} is there and it is non-zero use abbreviations
3435 instead of mappings. Don't forget to specify Insert and/or
3436 Command-line mode.
3437 Both the global mappings and the mappings local to the current
3438 buffer are checked for a match.
3439 If no matching mapping is found 0 is returned.
3440 The following characters are recognized in {mode}:
3441 n Normal mode
3442 v Visual mode
3443 o Operator-pending mode
3444 i Insert mode
3445 l Language-Argument ("r", "f", "t", etc.)
3446 c Command-line mode
3447 When {mode} is omitted, "nvo" is used.
3449 This function is useful to check if a mapping already exists
3450 to a function in a Vim script. Example: >
3451 :if !hasmapto('\ABCdoit')
3452 : map <Leader>d \ABCdoit
3453 :endif
3454 < This installs the mapping to "\ABCdoit" only if there isn't
3455 already a mapping to "\ABCdoit".
3457 histadd({history}, {item}) *histadd()*
3458 Add the String {item} to the history {history} which can be
3459 one of: *hist-names*
3460 "cmd" or ":" command line history
3461 "search" or "/" search pattern history
3462 "expr" or "=" typed expression history
3463 "input" or "@" input line history
3464 If {item} does already exist in the history, it will be
3465 shifted to become the newest entry.
3466 The result is a Number: 1 if the operation was successful,
3467 otherwise 0 is returned.
3469 Example: >
3470 :call histadd("input", strftime("%Y %b %d"))
3471 :let date=input("Enter date: ")
3472 < This function is not available in the |sandbox|.
3474 histdel({history} [, {item}]) *histdel()*
3475 Clear {history}, i.e. delete all its entries. See |hist-names|
3476 for the possible values of {history}.
3478 If the parameter {item} evaluates to a String, it is used as a
3479 regular expression. All entries matching that expression will
3480 be removed from the history (if there are any).
3481 Upper/lowercase must match, unless "\c" is used |/\c|.
3482 If {item} evaluates to a Number, it will be interpreted as
3483 an index, see |:history-indexing|. The respective entry will
3484 be removed if it exists.
3486 The result is a Number: 1 for a successful operation,
3487 otherwise 0 is returned.
3489 Examples:
3490 Clear expression register history: >
3491 :call histdel("expr")
3492 <
3493 Remove all entries starting with "*" from the search history: >
3494 :call histdel("/", '^\*')
3495 <
3496 The following three are equivalent: >
3497 :call histdel("search", histnr("search"))
3498 :call histdel("search", -1)
3499 :call histdel("search", '^'.histget("search", -1).'$')
3500 <
3501 To delete the last search pattern and use the last-but-one for
3502 the "n" command and 'hlsearch': >
3503 :call histdel("search", -1)
3504 :let @/ = histget("search", -1)
3506 histget({history} [, {index}]) *histget()*
3507 The result is a String, the entry with Number {index} from
3508 {history}. See |hist-names| for the possible values of
3509 {history}, and |:history-indexing| for {index}. If there is
3510 no such entry, an empty String is returned. When {index} is
3511 omitted, the most recent item from the history is used.
3513 Examples:
3514 Redo the second last search from history. >
3515 :execute '/' . histget("search", -2)
3517 < Define an Ex command ":H {num}" that supports re-execution of
3518 the {num}th entry from the output of |:history|. >
3519 :command -nargs=1 H execute histget("cmd", 0+<args>)
3520 <
3521 histnr({history}) *histnr()*
3522 The result is the Number of the current entry in {history}.
3523 See |hist-names| for the possible values of {history}.
3524 If an error occurred, -1 is returned.
3526 Example: >
3527 :let inp_index = histnr("expr")
3528 <
3529 hlexists({name}) *hlexists()*
3530 The result is a Number, which is non-zero if a highlight group
3531 called {name} exists. This is when the group has been
3532 defined in some way. Not necessarily when highlighting has
3533 been defined for it, it may also have been used for a syntax
3534 item.
3535 *highlight_exists()*
3536 Obsolete name: highlight_exists().
3538 *hlID()*
3539 hlID({name}) The result is a Number, which is the ID of the highlight group
3540 with name {name}. When the highlight group doesn't exist,
3541 zero is returned.
3542 This can be used to retrieve information about the highlight
3543 group. For example, to get the background color of the
3544 "Comment" group: >
3545 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
3546 < *highlightID()*
3547 Obsolete name: highlightID().
3549 hostname() *hostname()*
3550 The result is a String, which is the name of the machine on
3551 which Vim is currently running. Machine names greater than
3552 256 characters long are truncated.
3554 iconv({expr}, {from}, {to}) *iconv()*
3555 The result is a String, which is the text {expr} converted
3556 from encoding {from} to encoding {to}.
3557 When the conversion completely fails an empty string is
3558 returned. When some characters could not be converted they
3559 are replaced with "?".
3560 The encoding names are whatever the iconv() library function
3561 can accept, see ":!man 3 iconv".
3562 Most conversions require Vim to be compiled with the |+iconv|
3563 feature. Otherwise only UTF-8 to latin1 conversion and back
3564 can be done.
3565 This can be used to display messages with special characters,
3566 no matter what 'encoding' is set to. Write the message in
3567 UTF-8 and use: >
3568 echo iconv(utf8_str, "utf-8", &enc)
3569 < Note that Vim uses UTF-8 for all Unicode encodings, conversion
3570 from/to UCS-2 is automatically changed to use UTF-8. You
3571 cannot use UCS-2 in a string anyway, because of the NUL bytes.
3572 {only available when compiled with the +multi_byte feature}
3574 *indent()*
3575 indent({lnum}) The result is a Number, which is indent of line {lnum} in the
3576 current buffer. The indent is counted in spaces, the value
3577 of 'tabstop' is relevant. {lnum} is used just like in
3578 |getline()|.
3579 When {lnum} is invalid -1 is returned.
3582 index({list}, {expr} [, {start} [, {ic}]]) *index()*
3583 Return the lowest index in |List| {list} where the item has a
3584 value equal to {expr}. There is no automatic conversion, so
3585 the String "4" is different from the Number 4. And the number
3586 4 is different from the Float 4.0. The value of 'ignorecase'
3587 is not used here, case always matters.
3588 If {start} is given then start looking at the item with index
3589 {start} (may be negative for an item relative to the end).
3590 When {ic} is given and it is non-zero, ignore case. Otherwise
3591 case must match.
3592 -1 is returned when {expr} is not found in {list}.
3593 Example: >
3594 :let idx = index(words, "the")
3595 :if index(numbers, 123) >= 0
3598 input({prompt} [, {text} [, {completion}]]) *input()*
3599 The result is a String, which is whatever the user typed on
3600 the command-line. The {prompt} argument is either a prompt
3601 string, or a blank string (for no prompt). A '\n' can be used
3602 in the prompt to start a new line.
3603 The highlighting set with |:echohl| is used for the prompt.
3604 The input is entered just like a command-line, with the same
3605 editing commands and mappings. There is a separate history
3606 for lines typed for input().
3607 Example: >
3608 :if input("Coffee or beer? ") == "beer"
3609 : echo "Cheers!"
3610 :endif
3611 <
3612 If the optional {text} argument is present and not empty, this
3613 is used for the default reply, as if the user typed this.
3614 Example: >
3615 :let color = input("Color? ", "white")
3617 < The optional {completion} argument specifies the type of
3618 completion supported for the input. Without it completion is
3619 not performed. The supported completion types are the same as
3620 that can be supplied to a user-defined command using the
3621 "-complete=" argument. Refer to |:command-completion| for
3622 more information. Example: >
3623 let fname = input("File: ", "", "file")
3624 <
3625 NOTE: This function must not be used in a startup file, for
3626 the versions that only run in GUI mode (e.g., the Win32 GUI).
3627 Note: When input() is called from within a mapping it will
3628 consume remaining characters from that mapping, because a
3629 mapping is handled like the characters were typed.
3630 Use |inputsave()| before input() and |inputrestore()|
3631 after input() to avoid that. Another solution is to avoid
3632 that further characters follow in the mapping, e.g., by using
3633 |:execute| or |:normal|.
3635 Example with a mapping: >
3636 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR>
3637 :function GetFoo()
3638 : call inputsave()
3639 : let g:Foo = input("enter search pattern: ")
3640 : call inputrestore()
3641 :endfunction
3643 inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
3644 Like |input()|, but when the GUI is running and text dialogs
3645 are supported, a dialog window pops up to input the text.
3646 Example: >
3647 :let n = inputdialog("value for shiftwidth", &sw)
3648 :if n != ""
3649 : let &sw = n
3650 :endif
3651 < When the dialog is cancelled {cancelreturn} is returned. When
3652 omitted an empty string is returned.
3653 Hitting <Enter> works like pressing the OK button. Hitting
3654 <Esc> works like pressing the Cancel button.
3655 NOTE: Command-line completion is not supported.
3657 inputlist({textlist}) *inputlist()*
3658 {textlist} must be a |List| of strings. This |List| is
3659 displayed, one string per line. The user will be prompted to
3660 enter a number, which is returned.
3661 The user can also select an item by clicking on it with the
3662 mouse. For the first string 0 is returned. When clicking
3663 above the first item a negative number is returned. When
3664 clicking on the prompt one more than the length of {textlist}
3665 is returned.
3666 Make sure {textlist} has less than 'lines' entries, otherwise
3667 it won't work. It's a good idea to put the entry number at
3668 the start of the string. And put a prompt in the first item.
3669 Example: >
3670 let color = inputlist(['Select color:', '1. red',
3671 \ '2. green', '3. blue'])
3673 inputrestore() *inputrestore()*
3674 Restore typeahead that was saved with a previous |inputsave()|.
3675 Should be called the same number of times inputsave() is
3676 called. Calling it more often is harmless though.
3677 Returns 1 when there is nothing to restore, 0 otherwise.
3679 inputsave() *inputsave()*
3680 Preserve typeahead (also from mappings) and clear it, so that
3681 a following prompt gets input from the user. Should be
3682 followed by a matching inputrestore() after the prompt. Can
3683 be used several times, in which case there must be just as
3684 many inputrestore() calls.
3685 Returns 1 when out of memory, 0 otherwise.
3687 inputsecret({prompt} [, {text}]) *inputsecret()*
3688 This function acts much like the |input()| function with but
3689 two exceptions:
3690 a) the user's response will be displayed as a sequence of
3691 asterisks ("*") thereby keeping the entry secret, and
3692 b) the user's response will not be recorded on the input
3693 |history| stack.
3694 The result is a String, which is whatever the user actually
3695 typed on the command-line in response to the issued prompt.
3696 NOTE: Command-line completion is not supported.
3698 insert({list}, {item} [, {idx}]) *insert()*
3699 Insert {item} at the start of |List| {list}.
3700 If {idx} is specified insert {item} before the item with index
3701 {idx}. If {idx} is zero it goes before the first item, just
3702 like omitting {idx}. A negative {idx} is also possible, see
3703 |list-index|. -1 inserts just before the last item.
3704 Returns the resulting |List|. Examples: >
3705 :let mylist = insert([2, 3, 5], 1)
3706 :call insert(mylist, 4, -1)
3707 :call insert(mylist, 6, len(mylist))
3708 < The last example can be done simpler with |add()|.
3709 Note that when {item} is a |List| it is inserted as a single
3710 item. Use |extend()| to concatenate |Lists|.
3712 isdirectory({directory}) *isdirectory()*
3713 The result is a Number, which is non-zero when a directory
3714 with the name {directory} exists. If {directory} doesn't
3715 exist, or isn't a directory, the result is FALSE. {directory}
3716 is any expression, which is used as a String.
3718 islocked({expr}) *islocked()* *E786*
3719 The result is a Number, which is non-zero when {expr} is the
3720 name of a locked variable.
3721 {expr} must be the name of a variable, |List| item or
3722 |Dictionary| entry, not the variable itself! Example: >
3723 :let alist = [0, ['a', 'b'], 2, 3]
3724 :lockvar 1 alist
3725 :echo islocked('alist') " 1
3726 :echo islocked('alist[1]') " 0
3728 < When {expr} is a variable that does not exist you get an error
3729 message. Use |exists()| to check for existence.
3731 items({dict}) *items()*
3732 Return a |List| with all the key-value pairs of {dict}. Each
3733 |List| item is a list with two items: the key of a {dict}
3734 entry and the value of this entry. The |List| is in arbitrary
3735 order.
3738 join({list} [, {sep}]) *join()*
3739 Join the items in {list} together into one String.
3740 When {sep} is specified it is put in between the items. If
3741 {sep} is omitted a single space is used.
3742 Note that {sep} is not added at the end. You might want to
3743 add it there too: >
3744 let lines = join(mylist, "\n") . "\n"
3745 < String items are used as-is. |Lists| and |Dictionaries| are
3746 converted into a string like with |string()|.
3747 The opposite function is |split()|.
3749 keys({dict}) *keys()*
3750 Return a |List| with all the keys of {dict}. The |List| is in
3751 arbitrary order.
3753 *len()* *E701*
3754 len({expr}) The result is a Number, which is the length of the argument.
3755 When {expr} is a String or a Number the length in bytes is
3756 used, as with |strlen()|.
3757 When {expr} is a |List| the number of items in the |List| is
3758 returned.
3759 When {expr} is a |Dictionary| the number of entries in the
3760 |Dictionary| is returned.
3761 Otherwise an error is given.
3763 *libcall()* *E364* *E368*
3764 libcall({libname}, {funcname}, {argument})
3765 Call function {funcname} in the run-time library {libname}
3766 with single argument {argument}.
3767 This is useful to call functions in a library that you
3768 especially made to be used with Vim. Since only one argument
3769 is possible, calling standard library functions is rather
3770 limited.
3771 The result is the String returned by the function. If the
3772 function returns NULL, this will appear as an empty string ""
3773 to Vim.
3774 If the function returns a number, use libcallnr()!
3775 If {argument} is a number, it is passed to the function as an
3776 int; if {argument} is a string, it is passed as a
3777 null-terminated string.
3778 This function will fail in |restricted-mode|.
3780 libcall() allows you to write your own 'plug-in' extensions to
3781 Vim without having to recompile the program. It is NOT a
3782 means to call system functions! If you try to do so Vim will
3783 very probably crash.
3785 For Win32, the functions you write must be placed in a DLL
3786 and use the normal C calling convention (NOT Pascal which is
3787 used in Windows System DLLs). The function must take exactly
3788 one parameter, either a character pointer or a long integer,
3789 and must return a character pointer or NULL. The character
3790 pointer returned must point to memory that will remain valid
3791 after the function has returned (e.g. in static data in the
3792 DLL). If it points to allocated memory, that memory will
3793 leak away. Using a static buffer in the function should work,
3794 it's then freed when the DLL is unloaded.
3796 WARNING: If the function returns a non-valid pointer, Vim may
3797 crash! This also happens if the function returns a number,
3798 because Vim thinks it's a pointer.
3799 For Win32 systems, {libname} should be the filename of the DLL
3800 without the ".DLL" suffix. A full path is only required if
3801 the DLL is not in the usual places.
3802 For Unix: When compiling your own plugins, remember that the
3803 object code must be compiled as position-independent ('PIC').
3804 {only in Win32 and some Unix versions, when the |+libcall|
3805 feature is present}
3806 Examples: >
3807 :echo libcall("libc.so", "getenv", "HOME")
3808 <
3809 *libcallnr()*
3810 libcallnr({libname}, {funcname}, {argument})
3811 Just like |libcall()|, but used for a function that returns an
3812 int instead of a string.
3813 {only in Win32 on some Unix versions, when the |+libcall|
3814 feature is present}
3815 Examples: >
3816 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
3817 :call libcallnr("libc.so", "printf", "Hello World!\n")
3818 :call libcallnr("libc.so", "sleep", 10)
3819 <
3820 *line()*
3821 line({expr}) The result is a Number, which is the line number of the file
3822 position given with {expr}. The accepted positions are:
3823 . the cursor position
3824 $ the last line in the current buffer
3825 'x position of mark x (if the mark is not set, 0 is
3826 returned)
3827 w0 first line visible in current window
3828 w$ last line visible in current window
3829 v In Visual mode: the start of the Visual area (the
3830 cursor is the end). When not in Visual mode
3831 returns the cursor position. Differs from |'<| in
3832 that it's updated right away.
3833 Note that a mark in another file can be used. The line number
3834 then applies to another buffer.
3835 To get the column number use |col()|. To get both use
3836 |getpos()|.
3837 Examples: >
3838 line(".") line number of the cursor
3839 line("'t") line number of mark t
3840 line("'" . marker) line number of mark marker
3841 < *last-position-jump*
3842 This autocommand jumps to the last known position in a file
3843 just after opening it, if the '" mark is set: >
3844 :au BufReadPost * if line("'\"") > 1 && line("'\"") <= line("$") | exe "normal! g`\"" | endif
3846 line2byte({lnum}) *line2byte()*
3847 Return the byte count from the start of the buffer for line
3848 {lnum}. This includes the end-of-line character, depending on
3849 the 'fileformat' option for the current buffer. The first
3850 line returns 1.
3851 This can also be used to get the byte count for the line just
3852 below the last line: >
3853 line2byte(line("$") + 1)
3854 < This is the file size plus one.
3855 When {lnum} is invalid, or the |+byte_offset| feature has been
3856 disabled at compile time, -1 is returned.
3857 Also see |byte2line()|, |go| and |:goto|.
3859 lispindent({lnum}) *lispindent()*
3860 Get the amount of indent for line {lnum} according the lisp
3861 indenting rules, as with 'lisp'.
3862 The indent is counted in spaces, the value of 'tabstop' is
3863 relevant. {lnum} is used just like in |getline()|.
3864 When {lnum} is invalid or Vim was not compiled the
3865 |+lispindent| feature, -1 is returned.
3867 localtime() *localtime()*
3868 Return the current time, measured as seconds since 1st Jan
3869 1970. See also |strftime()| and |getftime()|.
3872 log({expr}) *log()*
3873 Return the natural logarithm (base e) of {expr} as a|Float|.
3874 {expr} must evaluate to a|Float|or a|Number|in (0,inf].
3875 Examples: >
3876 :echo log(10)
3877 < 2.302585 >
3878 :echo log(exp(5))
3879 < 5.0
3880 {only available when compiled with|+float|and extention}
3883 log10({expr}) *log10()*
3884 Return the logarithm of Float {expr} to base 10 as a |Float|.
3885 {expr} must evaluate to a |Float| or a |Number|.
3886 Examples: >
3887 :echo log10(1000)
3888 < 3.0 >
3889 :echo log10(0.01)
3890 < -2.0
3891 {only available when compiled with the |+float| feature}
3893 map({expr}, {string}) *map()*
3894 {expr} must be a |List| or a |Dictionary|.
3895 Replace each item in {expr} with the result of evaluating
3896 {string}.
3897 Inside {string} |v:val| has the value of the current item.
3898 For a |Dictionary| |v:key| has the key of the current item
3899 and for a |List| |v:key| has the index of the current item.
3900 Example: >
3901 :call map(mylist, '"> " . v:val . " <"')
3902 < This puts "> " before and " <" after each item in "mylist".
3904 Note that {string} is the result of an expression and is then
3905 used as an expression again. Often it is good to use a
3906 |literal-string| to avoid having to double backslashes. You
3907 still have to double ' quotes
3909 The operation is done in-place. If you want a |List| or
3910 |Dictionary| to remain unmodified make a copy first: >
3911 :let tlist = map(copy(mylist), ' & . "\t"')
3913 < Returns {expr}, the |List| or |Dictionary| that was filtered.
3914 When an error is encountered while evaluating {string} no
3915 further items in {expr} are processed.
3918 maparg({name}[, {mode} [, {abbr}]]) *maparg()*
3919 Return the rhs of mapping {name} in mode {mode}. When there
3920 is no mapping for {name}, an empty String is returned.
3921 {mode} can be one of these strings:
3922 "n" Normal
3923 "v" Visual
3924 "o" Operator-pending
3925 "i" Insert
3926 "c" Cmd-line
3927 "l" langmap |language-mapping|
3928 "" Normal, Visual and Operator-pending
3929 When {mode} is omitted, the modes for "" are used.
3930 When {abbr} is there and it is non-zero use abbreviations
3931 instead of mappings.
3932 The {name} can have special key names, like in the ":map"
3933 command. The returned String has special characters
3934 translated like in the output of the ":map" command listing.
3935 The mappings local to the current buffer are checked first,
3936 then the global mappings.
3937 This function can be used to map a key even when it's already
3938 mapped, and have it do the original mapping too. Sketch: >
3939 exe 'nnoremap <Tab> ==' . maparg('<Tab>', 'n')
3942 mapcheck({name}[, {mode} [, {abbr}]]) *mapcheck()*
3943 Check if there is a mapping that matches with {name} in mode
3944 {mode}. See |maparg()| for {mode} and special names in
3945 {name}.
3946 When {abbr} is there and it is non-zero use abbreviations
3947 instead of mappings.
3948 A match happens with a mapping that starts with {name} and
3949 with a mapping which is equal to the start of {name}.
3951 matches mapping "a" "ab" "abc" ~
3952 mapcheck("a") yes yes yes
3953 mapcheck("abc") yes yes yes
3954 mapcheck("ax") yes no no
3955 mapcheck("b") no no no
3957 The difference with maparg() is that mapcheck() finds a
3958 mapping that matches with {name}, while maparg() only finds a
3959 mapping for {name} exactly.
3960 When there is no mapping that starts with {name}, an empty
3961 String is returned. If there is one, the rhs of that mapping
3962 is returned. If there are several mappings that start with
3963 {name}, the rhs of one of them is returned.
3964 The mappings local to the current buffer are checked first,
3965 then the global mappings.
3966 This function can be used to check if a mapping can be added
3967 without being ambiguous. Example: >
3968 :if mapcheck("_vv") == ""
3969 : map _vv :set guifont=7x13<CR>
3970 :endif
3971 < This avoids adding the "_vv" mapping when there already is a
3972 mapping for "_v" or for "_vvv".
3974 match({expr}, {pat}[, {start}[, {count}]]) *match()*
3975 When {expr} is a |List| then this returns the index of the
3976 first item where {pat} matches. Each item is used as a
3977 String, |Lists| and |Dictionaries| are used as echoed.
3978 Otherwise, {expr} is used as a String. The result is a
3979 Number, which gives the index (byte offset) in {expr} where
3980 {pat} matches.
3981 A match at the first character or |List| item returns zero.
3982 If there is no match -1 is returned.
3983 Example: >
3984 :echo match("testing", "ing") " results in 4
3985 :echo match([1, 'x'], '\a') " results in 1
3986 < See |string-match| for how {pat} is used.
3987 *strpbrk()*
3988 Vim doesn't have a strpbrk() function. But you can do: >
3989 :let sepidx = match(line, '[.,;: \t]')
3990 < *strcasestr()*
3991 Vim doesn't have a strcasestr() function. But you can add
3992 "\c" to the pattern to ignore case: >
3993 :let idx = match(haystack, '\cneedle')
3994 <
3995 If {start} is given, the search starts from byte index
3996 {start} in a String or item {start} in a |List|.
3997 The result, however, is still the index counted from the
3998 first character/item. Example: >
3999 :echo match("testing", "ing", 2)
4000 < result is again "4". >
4001 :echo match("testing", "ing", 4)
4002 < result is again "4". >
4003 :echo match("testing", "t", 2)
4004 < result is "3".
4005 For a String, if {start} > 0 then it is like the string starts
4006 {start} bytes later, thus "^" will match at {start}. Except
4007 when {count} is given, then it's like matches before the
4008 {start} byte are ignored (this is a bit complicated to keep it
4009 backwards compatible).
4010 For a String, if {start} < 0, it will be set to 0. For a list
4011 the index is counted from the end.
4012 If {start} is out of range ({start} > strlen({expr}) for a
4013 String or {start} > len({expr}) for a |List|) -1 is returned.
4015 When {count} is given use the {count}'th match. When a match
4016 is found in a String the search for the next one starts one
4017 character further. Thus this example results in 1: >
4018 echo match("testing", "..", 0, 2)
4019 < In a |List| the search continues in the next item.
4020 Note that when {count} is added the way {start} works changes,
4021 see above.
4023 See |pattern| for the patterns that are accepted.
4024 The 'ignorecase' option is used to set the ignore-caseness of
4025 the pattern. 'smartcase' is NOT used. The matching is always
4026 done like 'magic' is set and 'cpoptions' is empty.
4028 *matchadd()* *E798* *E799* *E801*
4029 matchadd({group}, {pattern}[, {priority}[, {id}]])
4030 Defines a pattern to be highlighted in the current window (a
4031 "match"). It will be highlighted with {group}. Returns an
4032 identification number (ID), which can be used to delete the
4033 match using |matchdelete()|.
4035 The optional {priority} argument assigns a priority to the
4036 match. A match with a high priority will have its
4037 highlighting overrule that of a match with a lower priority.
4038 A priority is specified as an integer (negative numbers are no
4039 exception). If the {priority} argument is not specified, the
4040 default priority is 10. The priority of 'hlsearch' is zero,
4041 hence all matches with a priority greater than zero will
4042 overrule it. Syntax highlighting (see 'syntax') is a separate
4043 mechanism, and regardless of the chosen priority a match will
4044 always overrule syntax highlighting.
4046 The optional {id} argument allows the request for a specific
4047 match ID. If a specified ID is already taken, an error
4048 message will appear and the match will not be added. An ID
4049 is specified as a positive integer (zero excluded). IDs 1, 2
4050 and 3 are reserved for |:match|, |:2match| and |:3match|,
4051 respectively. If the {id} argument is not specified,
4052 |matchadd()| automatically chooses a free ID.
4054 The number of matches is not limited, as it is the case with
4055 the |:match| commands.
4057 Example: >
4058 :highlight MyGroup ctermbg=green guibg=green
4059 :let m = matchadd("MyGroup", "TODO")
4060 < Deletion of the pattern: >
4061 :call matchdelete(m)
4063 < A list of matches defined by |matchadd()| and |:match| are
4064 available from |getmatches()|. All matches can be deleted in
4065 one operation by |clearmatches()|.
4067 matcharg({nr}) *matcharg()*
4068 Selects the {nr} match item, as set with a |:match|,
4069 |:2match| or |:3match| command.
4070 Return a |List| with two elements:
4071 The name of the highlight group used
4072 The pattern used.
4073 When {nr} is not 1, 2 or 3 returns an empty |List|.
4074 When there is no match item set returns ['', ''].
4075 This is useful to save and restore a |:match|.
4076 Highlighting matches using the |:match| commands are limited
4077 to three matches. |matchadd()| does not have this limitation.
4079 matchdelete({id}) *matchdelete()* *E802* *E803*
4080 Deletes a match with ID {id} previously defined by |matchadd()|
4081 or one of the |:match| commands. Returns 0 if successful,
4082 otherwise -1. See example for |matchadd()|. All matches can
4083 be deleted in one operation by |clearmatches()|.
4085 matchend({expr}, {pat}[, {start}[, {count}]]) *matchend()*
4086 Same as |match()|, but return the index of first character
4087 after the match. Example: >
4088 :echo matchend("testing", "ing")
4089 < results in "7".
4090 *strspn()* *strcspn()*
4091 Vim doesn't have a strspn() or strcspn() function, but you can
4092 do it with matchend(): >
4093 :let span = matchend(line, '[a-zA-Z]')
4094 :let span = matchend(line, '[^a-zA-Z]')
4095 < Except that -1 is returned when there are no matches.
4097 The {start}, if given, has the same meaning as for |match()|. >
4098 :echo matchend("testing", "ing", 2)
4099 < results in "7". >
4100 :echo matchend("testing", "ing", 5)
4101 < result is "-1".
4102 When {expr} is a |List| the result is equal to |match()|.
4104 matchlist({expr}, {pat}[, {start}[, {count}]]) *matchlist()*
4105 Same as |match()|, but return a |List|. The first item in the
4106 list is the matched string, same as what matchstr() would
4107 return. Following items are submatches, like "\1", "\2", etc.
4108 in |:substitute|. When an optional submatch didn't match an
4109 empty string is used. Example: >
4110 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
4111 < Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
4112 When there is no match an empty list is returned.
4114 matchstr({expr}, {pat}[, {start}[, {count}]]) *matchstr()*
4115 Same as |match()|, but return the matched string. Example: >
4116 :echo matchstr("testing", "ing")
4117 < results in "ing".
4118 When there is no match "" is returned.
4119 The {start}, if given, has the same meaning as for |match()|. >
4120 :echo matchstr("testing", "ing", 2)
4121 < results in "ing". >
4122 :echo matchstr("testing", "ing", 5)
4123 < result is "".
4124 When {expr} is a |List| then the matching item is returned.
4125 The type isn't changed, it's not necessarily a String.
4127 *max()*
4128 max({list}) Return the maximum value of all items in {list}.
4129 If {list} is not a list or one of the items in {list} cannot
4130 be used as a Number this results in an error.
4131 An empty |List| results in zero.
4133 *min()*
4134 min({list}) Return the minimum value of all items in {list}.
4135 If {list} is not a list or one of the items in {list} cannot
4136 be used as a Number this results in an error.
4137 An empty |List| results in zero.
4139 *mkdir()* *E739*
4140 mkdir({name} [, {path} [, {prot}]])
4141 Create directory {name}.
4142 If {path} is "p" then intermediate directories are created as
4143 necessary. Otherwise it must be "".
4144 If {prot} is given it is used to set the protection bits of
4145 the new directory. The default is 0755 (rwxr-xr-x: r/w for
4146 the user readable for others). Use 0700 to make it unreadable
4147 for others. This is only used for the last part of {name}.
4148 Thus if you create /tmp/foo/bar then /tmp/foo will be created
4149 with 0755.
4150 Example: >
4151 :call mkdir($HOME . "/tmp/foo/bar", "p", 0700)
4152 < This function is not available in the |sandbox|.
4153 Not available on all systems. To check use: >
4154 :if exists("*mkdir")
4155 <
4156 *mode()*
4157 mode([expr]) Return a string that indicates the current mode.
4158 If [expr] is supplied and it evaluates to a non-zero Number or
4159 a non-empty String (|non-zero-arg|), then the full mode is
4160 returned, otherwise only the first letter is returned. Note
4161 that " " and "0" are also non-empty strings.
4163 n Normal
4164 no Operator-pending
4165 v Visual by character
4166 V Visual by line
4167 CTRL-V Visual blockwise
4168 s Select by character
4169 S Select by line
4170 CTRL-S Select blockwise
4171 i Insert
4172 R Replace |R|
4173 Rv Virtual Replace |gR|
4174 c Command-line
4175 cv Vim Ex mode |gQ|
4176 ce Normal Ex mode |Q|
4177 r Hit-enter prompt
4178 rm The -- more -- prompt
4179 r? A |:confirm| query of some sort
4180 ! Shell or external command is executing
4181 This is useful in the 'statusline' option or when used
4182 with |remote_expr()| In most other places it always returns
4183 "c" or "n".
4184 Also see |visualmode()|.
4186 mzeval({expr}) *mzeval()*
4187 Evaluate MzScheme expression {expr} and return its result
4188 convert to Vim data structures.
4189 Numbers and strings are returned as they are.
4190 Pairs (including lists and improper lists) and vectors are
4191 returned as Vim |Lists|.
4192 Hash tables are represented as Vim |Dictionary| type with keys
4193 converted to strings.
4194 All other types are converted to string with display function.
4195 Examples: >
4196 :mz (define l (list 1 2 3))
4197 :mz (define h (make-hash)) (hash-set! h "list" l)
4198 :echo mzeval("l")
4199 :echo mzeval("h")
4200 <
4201 {only available when compiled with the |+mzscheme| feature}
4203 nextnonblank({lnum}) *nextnonblank()*
4204 Return the line number of the first line at or below {lnum}
4205 that is not blank. Example: >
4206 if getline(nextnonblank(1)) =~ "Java"
4207 < When {lnum} is invalid or there is no non-blank line at or
4208 below it, zero is returned.
4209 See also |prevnonblank()|.
4211 nr2char({expr}) *nr2char()*
4212 Return a string with a single character, which has the number
4213 value {expr}. Examples: >
4214 nr2char(64) returns "@"
4215 nr2char(32) returns " "
4216 < The current 'encoding' is used. Example for "utf-8": >
4217 nr2char(300) returns I with bow character
4218 < Note that a NUL character in the file is specified with
4219 nr2char(10), because NULs are represented with newline
4220 characters. nr2char(0) is a real NUL and terminates the
4221 string, thus results in an empty string.
4223 *getpid()*
4224 getpid() Return a Number which is the process ID of the Vim process.
4225 On Unix and MS-Windows this is a unique number, until Vim
4226 exits. On MS-DOS it's always zero.
4228 *getpos()*
4229 getpos({expr}) Get the position for {expr}. For possible values of {expr}
4230 see |line()|.
4231 The result is a |List| with four numbers:
4232 [bufnum, lnum, col, off]
4233 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
4234 is the buffer number of the mark.
4235 "lnum" and "col" are the position in the buffer. The first
4236 column is 1.
4237 The "off" number is zero, unless 'virtualedit' is used. Then
4238 it is the offset in screen columns from the start of the
4239 character. E.g., a position within a <Tab> or after the last
4240 character.
4241 This can be used to save and restore the cursor position: >
4242 let save_cursor = getpos(".")
4243 MoveTheCursorAround
4244 call setpos('.', save_cursor)
4245 < Also see |setpos()|.
4247 pathshorten({expr}) *pathshorten()*
4248 Shorten directory names in the path {expr} and return the
4249 result. The tail, the file name, is kept as-is. The other
4250 components in the path are reduced to single letters. Leading
4251 '~' and '.' characters are kept. Example: >
4252 :echo pathshorten('~/.vim/autoload/myfile.vim')
4253 < ~/.v/a/myfile.vim ~
4254 It doesn't matter if the path exists or not.
4256 pow({x}, {y}) *pow()*
4257 Return the power of {x} to the exponent {y} as a |Float|.
4258 {x} and {y} must evaluate to a |Float| or a |Number|.
4259 Examples: >
4260 :echo pow(3, 3)
4261 < 27.0 >
4262 :echo pow(2, 16)
4263 < 65536.0 >
4264 :echo pow(32, 0.20)
4265 < 2.0
4266 {only available when compiled with the |+float| feature}
4268 prevnonblank({lnum}) *prevnonblank()*
4269 Return the line number of the first line at or above {lnum}
4270 that is not blank. Example: >
4271 let ind = indent(prevnonblank(v:lnum - 1))
4272 < When {lnum} is invalid or there is no non-blank line at or
4273 above it, zero is returned.
4274 Also see |nextnonblank()|.
4277 printf({fmt}, {expr1} ...) *printf()*
4278 Return a String with {fmt}, where "%" items are replaced by
4279 the formatted form of their respective arguments. Example: >
4280 printf("%4d: E%d %.30s", lnum, errno, msg)
4281 < May result in:
4282 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
4284 Often used items are:
4285 %s string
4286 %6s string right-aligned in 6 bytes
4287 %.9s string truncated to 9 bytes
4288 %c single byte
4289 %d decimal number
4290 %5d decimal number padded with spaces to 5 characters
4291 %x hex number
4292 %04x hex number padded with zeros to at least 4 characters
4293 %X hex number using upper case letters
4294 %o octal number
4295 %f floating point number in the form 123.456
4296 %e floating point number in the form 1.234e3
4297 %E floating point number in the form 1.234E3
4298 %g floating point number, as %f or %e depending on value
4299 %G floating point number, as %f or %E depending on value
4300 %% the % character itself
4302 Conversion specifications start with '%' and end with the
4303 conversion type. All other characters are copied unchanged to
4304 the result.
4306 The "%" starts a conversion specification. The following
4307 arguments appear in sequence:
4309 % [flags] [field-width] [.precision] type
4311 flags
4312 Zero or more of the following flags:
4314 # The value should be converted to an "alternate
4315 form". For c, d, and s conversions, this option
4316 has no effect. For o conversions, the precision
4317 of the number is increased to force the first
4318 character of the output string to a zero (except
4319 if a zero value is printed with an explicit
4320 precision of zero).
4321 For x and X conversions, a non-zero result has
4322 the string "0x" (or "0X" for X conversions)
4323 prepended to it.
4325 0 (zero) Zero padding. For all conversions the converted
4326 value is padded on the left with zeros rather
4327 than blanks. If a precision is given with a
4328 numeric conversion (d, o, x, and X), the 0 flag
4329 is ignored.
4331 - A negative field width flag; the converted value
4332 is to be left adjusted on the field boundary.
4333 The converted value is padded on the right with
4334 blanks, rather than on the left with blanks or
4335 zeros. A - overrides a 0 if both are given.
4337 ' ' (space) A blank should be left before a positive
4338 number produced by a signed conversion (d).
4340 + A sign must always be placed before a number
4341 produced by a signed conversion. A + overrides
4342 a space if both are used.
4344 field-width
4345 An optional decimal digit string specifying a minimum
4346 field width. If the converted value has fewer bytes
4347 than the field width, it will be padded with spaces on
4348 the left (or right, if the left-adjustment flag has
4349 been given) to fill out the field width.
4351 .precision
4352 An optional precision, in the form of a period '.'
4353 followed by an optional digit string. If the digit
4354 string is omitted, the precision is taken as zero.
4355 This gives the minimum number of digits to appear for
4356 d, o, x, and X conversions, or the maximum number of
4357 bytes to be printed from a string for s conversions.
4358 For floating point it is the number of digits after
4359 the decimal point.
4361 type
4362 A character that specifies the type of conversion to
4363 be applied, see below.
4365 A field width or precision, or both, may be indicated by an
4366 asterisk '*' instead of a digit string. In this case, a
4367 Number argument supplies the field width or precision. A
4368 negative field width is treated as a left adjustment flag
4369 followed by a positive field width; a negative precision is
4370 treated as though it were missing. Example: >
4371 :echo printf("%d: %.*s", nr, width, line)
4372 < This limits the length of the text used from "line" to
4373 "width" bytes.
4375 The conversion specifiers and their meanings are:
4377 *printf-d* *printf-o* *printf-x* *printf-X*
4378 doxX The Number argument is converted to signed decimal
4379 (d), unsigned octal (o), or unsigned hexadecimal (x
4380 and X) notation. The letters "abcdef" are used for
4381 x conversions; the letters "ABCDEF" are used for X
4382 conversions.
4383 The precision, if any, gives the minimum number of
4384 digits that must appear; if the converted value
4385 requires fewer digits, it is padded on the left with
4386 zeros.
4387 In no case does a non-existent or small field width
4388 cause truncation of a numeric field; if the result of
4389 a conversion is wider than the field width, the field
4390 is expanded to contain the conversion result.
4392 *printf-c*
4393 c The Number argument is converted to a byte, and the
4394 resulting character is written.
4396 *printf-s*
4397 s The text of the String argument is used. If a
4398 precision is specified, no more bytes than the number
4399 specified are used.
4401 *printf-f* *E807*
4402 f The Float argument is converted into a string of the
4403 form 123.456. The precision specifies the number of
4404 digits after the decimal point. When the precision is
4405 zero the decimal point is omitted. When the precision
4406 is not specified 6 is used. A really big number
4407 (out of range or dividing by zero) results in "inf".
4408 "0.0 / 0.0" results in "nan".
4409 Example: >
4410 echo printf("%.2f", 12.115)
4411 < 12.12
4412 Note that roundoff depends on the system libraries.
4413 Use |round()| when in doubt.
4415 *printf-e* *printf-E*
4416 e E The Float argument is converted into a string of the
4417 form 1.234e+03 or 1.234E+03 when using 'E'. The
4418 precision specifies the number of digits after the
4419 decimal point, like with 'f'.
4421 *printf-g* *printf-G*
4422 g G The Float argument is converted like with 'f' if the
4423 value is between 0.001 (inclusive) and 10000000.0
4424 (exclusive). Otherwise 'e' is used for 'g' and 'E'
4425 for 'G'. When no precision is specified superfluous
4426 zeroes and '+' signs are removed, except for the zero
4427 immediately after the decimal point. Thus 10000000.0
4428 results in 1.0e7.
4430 *printf-%*
4431 % A '%' is written. No argument is converted. The
4432 complete conversion specification is "%%".
4434 When a Number argument is expected a String argument is also
4435 accepted and automatically converted.
4436 When a Float or String argument is expected a Number argument
4437 is also accepted and automatically converted.
4438 Any other argument type results in an error message.
4440 *E766* *E767*
4441 The number of {exprN} arguments must exactly match the number
4442 of "%" items. If there are not sufficient or too many
4443 arguments an error is given. Up to 18 arguments can be used.
4446 pumvisible() *pumvisible()*
4447 Returns non-zero when the popup menu is visible, zero
4448 otherwise. See |ins-completion-menu|.
4449 This can be used to avoid some things that would remove the
4450 popup menu.
4452 *E726* *E727*
4453 range({expr} [, {max} [, {stride}]]) *range()*
4454 Returns a |List| with Numbers:
4455 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
4456 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
4457 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
4458 {max}] (increasing {expr} with {stride} each time, not
4459 producing a value past {max}).
4460 When the maximum is one before the start the result is an
4461 empty list. When the maximum is more than one before the
4462 start this is an error.
4463 Examples: >
4464 range(4) " [0, 1, 2, 3]
4465 range(2, 4) " [2, 3, 4]
4466 range(2, 9, 3) " [2, 5, 8]
4467 range(2, -2, -1) " [2, 1, 0, -1, -2]
4468 range(0) " []
4469 range(2, 0) " error!
4470 <
4471 *readfile()*
4472 readfile({fname} [, {binary} [, {max}]])
4473 Read file {fname} and return a |List|, each line of the file
4474 as an item. Lines broken at NL characters. Macintosh files
4475 separated with CR will result in a single long line (unless a
4476 NL appears somewhere).
4477 When {binary} is equal to "b" binary mode is used:
4478 - When the last line ends in a NL an extra empty list item is
4479 added.
4480 - No CR characters are removed.
4481 Otherwise:
4482 - CR characters that appear before a NL are removed.
4483 - Whether the last line ends in a NL or not does not matter.
4484 All NUL characters are replaced with a NL character.
4485 When {max} is given this specifies the maximum number of lines
4486 to be read. Useful if you only want to check the first ten
4487 lines of a file: >
4488 :for line in readfile(fname, '', 10)
4489 : if line =~ 'Date' | echo line | endif
4490 :endfor
4491 < When {max} is negative -{max} lines from the end of the file
4492 are returned, or as many as there are.
4493 When {max} is zero the result is an empty list.
4494 Note that without {max} the whole file is read into memory.
4495 Also note that there is no recognition of encoding. Read a
4496 file into a buffer if you need to.
4497 When the file can't be opened an error message is given and
4498 the result is an empty list.
4499 Also see |writefile()|.
4501 reltime([{start} [, {end}]]) *reltime()*
4502 Return an item that represents a time value. The format of
4503 the item depends on the system. It can be passed to
4504 |reltimestr()| to convert it to a string.
4505 Without an argument it returns the current time.
4506 With one argument is returns the time passed since the time
4507 specified in the argument.
4508 With two arguments it returns the time passed between {start}
4509 and {end}.
4510 The {start} and {end} arguments must be values returned by
4511 reltime().
4512 {only available when compiled with the +reltime feature}
4514 reltimestr({time}) *reltimestr()*
4515 Return a String that represents the time value of {time}.
4516 This is the number of seconds, a dot and the number of
4517 microseconds. Example: >
4518 let start = reltime()
4519 call MyFunction()
4520 echo reltimestr(reltime(start))
4521 < Note that overhead for the commands will be added to the time.
4522 The accuracy depends on the system.
4523 Leading spaces are used to make the string align nicely. You
4524 can use split() to remove it. >
4525 echo split(reltimestr(reltime(start)))[0]
4526 < Also see |profiling|.
4527 {only available when compiled with the +reltime feature}
4529 *remote_expr()* *E449*
4530 remote_expr({server}, {string} [, {idvar}])
4531 Send the {string} to {server}. The string is sent as an
4532 expression and the result is returned after evaluation.
4533 The result must be a String or a |List|. A |List| is turned
4534 into a String by joining the items with a line break in
4535 between (not at the end), like with join(expr, "\n").
4536 If {idvar} is present, it is taken as the name of a
4537 variable and a {serverid} for later use with
4538 remote_read() is stored there.
4539 See also |clientserver| |RemoteReply|.
4540 This function is not available in the |sandbox|.
4541 {only available when compiled with the |+clientserver| feature}
4542 Note: Any errors will cause a local error message to be issued
4543 and the result will be the empty string.
4544 Examples: >
4545 :echo remote_expr("gvim", "2+2")
4546 :echo remote_expr("gvim1", "b:current_syntax")
4547 <
4549 remote_foreground({server}) *remote_foreground()*
4550 Move the Vim server with the name {server} to the foreground.
4551 This works like: >
4552 remote_expr({server}, "foreground()")
4553 < Except that on Win32 systems the client does the work, to work
4554 around the problem that the OS doesn't always allow the server
4555 to bring itself to the foreground.
4556 Note: This does not restore the window if it was minimized,
4557 like foreground() does.
4558 This function is not available in the |sandbox|.
4559 {only in the Win32, Athena, Motif and GTK GUI versions and the
4560 Win32 console version}
4563 remote_peek({serverid} [, {retvar}]) *remote_peek()*
4564 Returns a positive number if there are available strings
4565 from {serverid}. Copies any reply string into the variable
4566 {retvar} if specified. {retvar} must be a string with the
4567 name of a variable.
4568 Returns zero if none are available.
4569 Returns -1 if something is wrong.
4570 See also |clientserver|.
4571 This function is not available in the |sandbox|.
4572 {only available when compiled with the |+clientserver| feature}
4573 Examples: >
4574 :let repl = ""
4575 :echo "PEEK: ".remote_peek(id, "repl").": ".repl
4577 remote_read({serverid}) *remote_read()*
4578 Return the oldest available reply from {serverid} and consume
4579 it. It blocks until a reply is available.
4580 See also |clientserver|.
4581 This function is not available in the |sandbox|.
4582 {only available when compiled with the |+clientserver| feature}
4583 Example: >
4584 :echo remote_read(id)
4585 <
4586 *remote_send()* *E241*
4587 remote_send({server}, {string} [, {idvar}])
4588 Send the {string} to {server}. The string is sent as input
4589 keys and the function returns immediately. At the Vim server
4590 the keys are not mapped |:map|.
4591 If {idvar} is present, it is taken as the name of a variable
4592 and a {serverid} for later use with remote_read() is stored
4593 there.
4594 See also |clientserver| |RemoteReply|.
4595 This function is not available in the |sandbox|.
4596 {only available when compiled with the |+clientserver| feature}
4597 Note: Any errors will be reported in the server and may mess
4598 up the display.
4599 Examples: >
4600 :echo remote_send("gvim", ":DropAndReply ".file, "serverid").
4601 \ remote_read(serverid)
4603 :autocmd NONE RemoteReply *
4604 \ echo remote_read(expand("<amatch>"))
4605 :echo remote_send("gvim", ":sleep 10 | echo ".
4606 \ 'server2client(expand("<client>"), "HELLO")<CR>')
4607 <
4608 remove({list}, {idx} [, {end}]) *remove()*
4609 Without {end}: Remove the item at {idx} from |List| {list} and
4610 return the item.
4611 With {end}: Remove items from {idx} to {end} (inclusive) and
4612 return a List with these items. When {idx} points to the same
4613 item as {end} a list with one item is returned. When {end}
4614 points to an item before {idx} this is an error.
4615 See |list-index| for possible values of {idx} and {end}.
4616 Example: >
4617 :echo "last item: " . remove(mylist, -1)
4618 :call remove(mylist, 0, 9)
4619 remove({dict}, {key})
4620 Remove the entry from {dict} with key {key}. Example: >
4621 :echo "removed " . remove(dict, "one")
4622 < If there is no {key} in {dict} this is an error.
4624 Use |delete()| to remove a file.
4626 rename({from}, {to}) *rename()*
4627 Rename the file by the name {from} to the name {to}. This
4628 should also work to move files across file systems. The
4629 result is a Number, which is 0 if the file was renamed
4630 successfully, and non-zero when the renaming failed.
4631 NOTE: If {to} exists it is overwritten without warning.
4632 This function is not available in the |sandbox|.
4634 repeat({expr}, {count}) *repeat()*
4635 Repeat {expr} {count} times and return the concatenated
4636 result. Example: >
4637 :let separator = repeat('-', 80)
4638 < When {count} is zero or negative the result is empty.
4639 When {expr} is a |List| the result is {expr} concatenated
4640 {count} times. Example: >
4641 :let longlist = repeat(['a', 'b'], 3)
4642 < Results in ['a', 'b', 'a', 'b', 'a', 'b'].
4645 resolve({filename}) *resolve()* *E655*
4646 On MS-Windows, when {filename} is a shortcut (a .lnk file),
4647 returns the path the shortcut points to in a simplified form.
4648 On Unix, repeat resolving symbolic links in all path
4649 components of {filename} and return the simplified result.
4650 To cope with link cycles, resolving of symbolic links is
4651 stopped after 100 iterations.
4652 On other systems, return the simplified {filename}.
4653 The simplification step is done as by |simplify()|.
4654 resolve() keeps a leading path component specifying the
4655 current directory (provided the result is still a relative
4656 path name) and also keeps a trailing path separator.
4658 *reverse()*
4659 reverse({list}) Reverse the order of items in {list} in-place. Returns
4660 {list}.
4661 If you want a list to remain unmodified make a copy first: >
4662 :let revlist = reverse(copy(mylist))
4664 round({expr}) *round()*
4665 Round off {expr} to the nearest integral value and return it
4666 as a |Float|. If {expr} lies halfway between two integral
4667 values, then use the larger one (away from zero).
4668 {expr} must evaluate to a |Float| or a |Number|.
4669 Examples: >
4670 echo round(0.456)
4671 < 0.0 >
4672 echo round(4.5)
4673 < 5.0 >
4674 echo round(-4.5)
4675 < -5.0
4676 {only available when compiled with the |+float| feature}
4679 search({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *search()*
4680 Search for regexp pattern {pattern}. The search starts at the
4681 cursor position (you can use |cursor()| to set it).
4683 {flags} is a String, which can contain these character flags:
4684 'b' search backward instead of forward
4685 'c' accept a match at the cursor position
4686 'e' move to the End of the match
4687 'n' do Not move the cursor
4688 'p' return number of matching sub-pattern (see below)
4689 's' set the ' mark at the previous location of the cursor
4690 'w' wrap around the end of the file
4691 'W' don't wrap around the end of the file
4692 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
4694 If the 's' flag is supplied, the ' mark is set, only if the
4695 cursor is moved. The 's' flag cannot be combined with the 'n'
4696 flag.
4698 'ignorecase', 'smartcase' and 'magic' are used.
4700 When the {stopline} argument is given then the search stops
4701 after searching this line. This is useful to restrict the
4702 search to a range of lines. Examples: >
4703 let match = search('(', 'b', line("w0"))
4704 let end = search('END', '', line("w$"))
4705 < When {stopline} is used and it is not zero this also implies
4706 that the search does not wrap around the end of the file.
4707 A zero value is equal to not giving the argument.
4709 When the {timeout} argument is given the search stops when
4710 more than this many milli seconds have passed. Thus when
4711 {timeout} is 500 the search stops after half a second.
4712 The value must not be negative. A zero value is like not
4713 giving the argument.
4714 {only available when compiled with the +reltime feature}
4716 If there is no match a 0 is returned and the cursor doesn't
4717 move. No error message is given.
4718 When a match has been found its line number is returned.
4719 *search()-sub-match*
4720 With the 'p' flag the returned value is one more than the
4721 first sub-match in \(\). One if none of them matched but the
4722 whole pattern did match.
4723 To get the column number too use |searchpos()|.
4725 The cursor will be positioned at the match, unless the 'n'
4726 flag is used.
4728 Example (goes over all files in the argument list): >
4729 :let n = 1
4730 :while n <= argc() " loop over all files in arglist
4731 : exe "argument " . n
4732 : " start at the last char in the file and wrap for the
4733 : " first search to find match at start of file
4734 : normal G$
4735 : let flags = "w"
4736 : while search("foo", flags) > 0
4737 : s/foo/bar/g
4738 : let flags = "W"
4739 : endwhile
4740 : update " write the file if modified
4741 : let n = n + 1
4742 :endwhile
4743 <
4744 Example for using some flags: >
4745 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
4746 < This will search for the keywords "if", "else", and "endif"
4747 under or after the cursor. Because of the 'p' flag, it
4748 returns 1, 2, or 3 depending on which keyword is found, or 0
4749 if the search fails. With the cursor on the first word of the
4750 line:
4751 if (foo == 0) | let foo = foo + 1 | endif ~
4752 the function returns 1. Without the 'c' flag, the function
4753 finds the "endif" and returns 3. The same thing happens
4754 without the 'e' flag if the cursor is on the "f" of "if".
4755 The 'n' flag tells the function not to move the cursor.
4758 searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
4759 Search for the declaration of {name}.
4761 With a non-zero {global} argument it works like |gD|, find
4762 first match in the file. Otherwise it works like |gd|, find
4763 first match in the function.
4765 With a non-zero {thisblock} argument matches in a {} block
4766 that ends before the cursor position are ignored. Avoids
4767 finding variable declarations only valid in another scope.
4769 Moves the cursor to the found match.
4770 Returns zero for success, non-zero for failure.
4771 Example: >
4772 if searchdecl('myvar') == 0
4773 echo getline('.')
4774 endif
4775 <
4776 *searchpair()*
4777 searchpair({start}, {middle}, {end} [, {flags} [, {skip}
4778 [, {stopline} [, {timeout}]]]])
4779 Search for the match of a nested start-end pair. This can be
4780 used to find the "endif" that matches an "if", while other
4781 if/endif pairs in between are ignored.
4782 The search starts at the cursor. The default is to search
4783 forward, include 'b' in {flags} to search backward.
4784 If a match is found, the cursor is positioned at it and the
4785 line number is returned. If no match is found 0 or -1 is
4786 returned and the cursor doesn't move. No error message is
4787 given.
4789 {start}, {middle} and {end} are patterns, see |pattern|. They
4790 must not contain \( \) pairs. Use of \%( \) is allowed. When
4791 {middle} is not empty, it is found when searching from either
4792 direction, but only when not in a nested start-end pair. A
4793 typical use is: >
4794 searchpair('\<if\>', '\<else\>', '\<endif\>')
4795 < By leaving {middle} empty the "else" is skipped.
4797 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
4798 |search()|. Additionally:
4799 'r' Repeat until no more matches found; will find the
4800 outer pair. Implies the 'W' flag.
4801 'm' Return number of matches instead of line number with
4802 the match; will be > 1 when 'r' is used.
4803 Note: it's nearly always a good idea to use the 'W' flag, to
4804 avoid wrapping around the end of the file.
4806 When a match for {start}, {middle} or {end} is found, the
4807 {skip} expression is evaluated with the cursor positioned on
4808 the start of the match. It should return non-zero if this
4809 match is to be skipped. E.g., because it is inside a comment
4810 or a string.
4811 When {skip} is omitted or empty, every match is accepted.
4812 When evaluating {skip} causes an error the search is aborted
4813 and -1 returned.
4815 For {stopline} and {timeout} see |search()|.
4817 The value of 'ignorecase' is used. 'magic' is ignored, the
4818 patterns are used like it's on.
4820 The search starts exactly at the cursor. A match with
4821 {start}, {middle} or {end} at the next character, in the
4822 direction of searching, is the first one found. Example: >
4823 if 1
4824 if 2
4825 endif 2
4826 endif 1
4827 < When starting at the "if 2", with the cursor on the "i", and
4828 searching forwards, the "endif 2" is found. When starting on
4829 the character just before the "if 2", the "endif 1" will be
4830 found. That's because the "if 2" will be found first, and
4831 then this is considered to be a nested if/endif from "if 2" to
4832 "endif 2".
4833 When searching backwards and {end} is more than one character,
4834 it may be useful to put "\zs" at the end of the pattern, so
4835 that when the cursor is inside a match with the end it finds
4836 the matching start.
4838 Example, to find the "endif" command in a Vim script: >
4840 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
4841 \ 'getline(".") =~ "^\\s*\""')
4843 < The cursor must be at or after the "if" for which a match is
4844 to be found. Note that single-quote strings are used to avoid
4845 having to double the backslashes. The skip expression only
4846 catches comments at the start of a line, not after a command.
4847 Also, a word "en" or "if" halfway a line is considered a
4848 match.
4849 Another example, to search for the matching "{" of a "}": >
4851 :echo searchpair('{', '', '}', 'bW')
4853 < This works when the cursor is at or before the "}" for which a
4854 match is to be found. To reject matches that syntax
4855 highlighting recognized as strings: >
4857 :echo searchpair('{', '', '}', 'bW',
4858 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
4859 <
4860 *searchpairpos()*
4861 searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
4862 [, {stopline} [, {timeout}]]]])
4863 Same as |searchpair()|, but returns a |List| with the line and
4864 column position of the match. The first element of the |List|
4865 is the line number and the second element is the byte index of
4866 the column position of the match. If no match is found,
4867 returns [0, 0].
4868 >
4869 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
4870 <
4871 See |match-parens| for a bigger and more useful example.
4873 searchpos({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *searchpos()*
4874 Same as |search()|, but returns a |List| with the line and
4875 column position of the match. The first element of the |List|
4876 is the line number and the second element is the byte index of
4877 the column position of the match. If no match is found,
4878 returns [0, 0].
4879 Example: >
4880 :let [lnum, col] = searchpos('mypattern', 'n')
4882 < When the 'p' flag is given then there is an extra item with
4883 the sub-pattern match number |search()-sub-match|. Example: >
4884 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
4885 < In this example "submatch" is 2 when a lowercase letter is
4886 found |/\l|, 3 when an uppercase letter is found |/\u|.
4888 server2client( {clientid}, {string}) *server2client()*
4889 Send a reply string to {clientid}. The most recent {clientid}
4890 that sent a string can be retrieved with expand("<client>").
4891 {only available when compiled with the |+clientserver| feature}
4892 Note:
4893 This id has to be stored before the next command can be
4894 received. I.e. before returning from the received command and
4895 before calling any commands that waits for input.
4896 See also |clientserver|.
4897 Example: >
4898 :echo server2client(expand("<client>"), "HELLO")
4899 <
4900 serverlist() *serverlist()*
4901 Return a list of available server names, one per line.
4902 When there are no servers or the information is not available
4903 an empty string is returned. See also |clientserver|.
4904 {only available when compiled with the |+clientserver| feature}
4905 Example: >
4906 :echo serverlist()
4907 <
4908 setbufvar({expr}, {varname}, {val}) *setbufvar()*
4909 Set option or local variable {varname} in buffer {expr} to
4910 {val}.
4911 This also works for a global or local window option, but it
4912 doesn't work for a global or local window variable.
4913 For a local window option the global value is unchanged.
4914 For the use of {expr}, see |bufname()| above.
4915 Note that the variable name without "b:" must be used.
4916 Examples: >
4917 :call setbufvar(1, "&mod", 1)
4918 :call setbufvar("todo", "myvar", "foobar")
4919 < This function is not available in the |sandbox|.
4921 setcmdpos({pos}) *setcmdpos()*
4922 Set the cursor position in the command line to byte position
4923 {pos}. The first position is 1.
4924 Use |getcmdpos()| to obtain the current position.
4925 Only works while editing the command line, thus you must use
4926 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
4927 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
4928 set after the command line is set to the expression. For
4929 |c_CTRL-R_=| it is set after evaluating the expression but
4930 before inserting the resulting text.
4931 When the number is too big the cursor is put at the end of the
4932 line. A number smaller than one has undefined results.
4933 Returns 0 when successful, 1 when not editing the command
4934 line.
4936 setline({lnum}, {text}) *setline()*
4937 Set line {lnum} of the current buffer to {text}.
4938 {lnum} is used like with |getline()|.
4939 When {lnum} is just below the last line the {text} will be
4940 added as a new line.
4941 If this succeeds, 0 is returned. If this fails (most likely
4942 because {lnum} is invalid) 1 is returned. Example: >
4943 :call setline(5, strftime("%c"))
4944 < When {text} is a |List| then line {lnum} and following lines
4945 will be set to the items in the list. Example: >
4946 :call setline(5, ['aaa', 'bbb', 'ccc'])
4947 < This is equivalent to: >
4948 :for [n, l] in [[5, 6, 7], ['aaa', 'bbb', 'ccc']]
4949 : call setline(n, l)
4950 :endfor
4951 < Note: The '[ and '] marks are not set.
4953 setloclist({nr}, {list} [, {action}]) *setloclist()*
4954 Create or replace or add to the location list for window {nr}.
4955 When {nr} is zero the current window is used. For a location
4956 list window, the displayed location list is modified. For an
4957 invalid window number {nr}, -1 is returned.
4958 Otherwise, same as |setqflist()|.
4959 Also see |location-list|.
4961 setmatches({list}) *setmatches()*
4962 Restores a list of matches saved by |getmatches()|. Returns 0
4963 if successful, otherwise -1. All current matches are cleared
4964 before the list is restored. See example for |getmatches()|.
4966 *setpos()*
4967 setpos({expr}, {list})
4968 Set the position for {expr}. Possible values:
4969 . the cursor
4970 'x mark x
4972 {list} must be a |List| with four numbers:
4973 [bufnum, lnum, col, off]
4975 "bufnum" is the buffer number. Zero can be used for the
4976 current buffer. Setting the cursor is only possible for
4977 the current buffer. To set a mark in another buffer you can
4978 use the |bufnr()| function to turn a file name into a buffer
4979 number.
4980 Does not change the jumplist.
4982 "lnum" and "col" are the position in the buffer. The first
4983 column is 1. Use a zero "lnum" to delete a mark. If "col" is
4984 smaller than 1 then 1 is used.
4986 The "off" number is only used when 'virtualedit' is set. Then
4987 it is the offset in screen columns from the start of the
4988 character. E.g., a position within a <Tab> or after the last
4989 character.
4991 Returns 0 when the position could be set, -1 otherwise.
4992 An error message is given if {expr} is invalid.
4994 Also see |getpos()|
4996 This does not restore the preferred column for moving
4997 vertically. See |winrestview()| for that.
5000 setqflist({list} [, {action}]) *setqflist()*
5001 Create or replace or add to the quickfix list using the items
5002 in {list}. Each item in {list} is a dictionary.
5003 Non-dictionary items in {list} are ignored. Each dictionary
5004 item can contain the following entries:
5006 bufnr buffer number; must be the number of a valid
5007 buffer
5008 filename name of a file; only used when "bufnr" is not
5009 present or it is invalid.
5010 lnum line number in the file
5011 pattern search pattern used to locate the error
5012 col column number
5013 vcol when non-zero: "col" is visual column
5014 when zero: "col" is byte index
5015 nr error number
5016 text description of the error
5017 type single-character error type, 'E', 'W', etc.
5019 The "col", "vcol", "nr", "type" and "text" entries are
5020 optional. Either "lnum" or "pattern" entry can be used to
5021 locate a matching error line.
5022 If the "filename" and "bufnr" entries are not present or
5023 neither the "lnum" or "pattern" entries are present, then the
5024 item will not be handled as an error line.
5025 If both "pattern" and "lnum" are present then "pattern" will
5026 be used.
5027 Note that the list is not exactly the same as what
5028 |getqflist()| returns.
5030 If {action} is set to 'a', then the items from {list} are
5031 added to the existing quickfix list. If there is no existing
5032 list, then a new list is created. If {action} is set to 'r',
5033 then the items from the current quickfix list are replaced
5034 with the items from {list}. If {action} is not present or is
5035 set to ' ', then a new list is created.
5037 Returns zero for success, -1 for failure.
5039 This function can be used to create a quickfix list
5040 independent of the 'errorformat' setting. Use a command like
5041 ":cc 1" to jump to the first position.
5044 *setreg()*
5045 setreg({regname}, {value} [,{options}])
5046 Set the register {regname} to {value}.
5047 If {options} contains "a" or {regname} is upper case,
5048 then the value is appended.
5049 {options} can also contains a register type specification:
5050 "c" or "v" |characterwise| mode
5051 "l" or "V" |linewise| mode
5052 "b" or "<CTRL-V>" |blockwise-visual| mode
5053 If a number immediately follows "b" or "<CTRL-V>" then this is
5054 used as the width of the selection - if it is not specified
5055 then the width of the block is set to the number of characters
5056 in the longest line (counting a <Tab> as 1 character).
5058 If {options} contains no register settings, then the default
5059 is to use character mode unless {value} ends in a <NL>.
5060 Setting the '=' register is not possible.
5061 Returns zero for success, non-zero for failure.
5063 Examples: >
5064 :call setreg(v:register, @*)
5065 :call setreg('*', @%, 'ac')
5066 :call setreg('a', "1\n2\n3", 'b5')
5068 < This example shows using the functions to save and restore a
5069 register. >
5070 :let var_a = getreg('a', 1)
5071 :let var_amode = getregtype('a')
5072 ....
5073 :call setreg('a', var_a, var_amode)
5075 < You can also change the type of a register by appending
5076 nothing: >
5077 :call setreg('a', '', 'al')
5079 settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
5080 Set option or local variable {varname} in window {winnr} to
5081 {val}.
5082 Tabs are numbered starting with one. For the current tabpage
5083 use |setwinvar()|.
5084 When {winnr} is zero the current window is used.
5085 This also works for a global or local buffer option, but it
5086 doesn't work for a global or local buffer variable.
5087 For a local buffer option the global value is unchanged.
5088 Note that the variable name without "w:" must be used.
5089 Vim briefly goes to the tab page {tabnr}, this may trigger
5090 TabLeave and TabEnter autocommands.
5091 Examples: >
5092 :call settabwinvar(1, 1, "&list", 0)
5093 :call settabwinvar(3, 2, "myvar", "foobar")
5094 < This function is not available in the |sandbox|.
5096 setwinvar({nr}, {varname}, {val}) *setwinvar()*
5097 Like |settabwinvar()| for the current tab page.
5098 Examples: >
5099 :call setwinvar(1, "&list", 0)
5100 :call setwinvar(2, "myvar", "foobar")
5102 shellescape({string} [, {special}]) *shellescape()*
5103 Escape {string} for use as a shell command argument.
5104 On MS-Windows and MS-DOS, when 'shellslash' is not set, it
5105 will enclose {string} in double quotes and double all double
5106 quotes within {string}.
5107 For other systems, it will enclose {string} in single quotes
5108 and replace all "'" with "'\''".
5109 When the {special} argument is present and it's a non-zero
5110 Number or a non-empty String (|non-zero-arg|), then special
5111 items such as "!", "%", "#" and "<cword>" will be preceded by
5112 a backslash. This backslash will be removed again by the |:!|
5113 command.
5114 The "!" character will be escaped (again with a |non-zero-arg|
5115 {special}) when 'shell' contains "csh" in the tail. That is
5116 because for csh and tcsh "!" is used for history replacement
5117 even when inside single quotes.
5118 The <NL> character is also escaped. With a |non-zero-arg|
5119 {special} and 'shell' containing "csh" in the tail it's
5120 escaped a second time.
5121 Example of use with a |:!| command: >
5122 :exe '!dir ' . shellescape(expand('<cfile>'), 1)
5123 < This results in a directory listing for the file under the
5124 cursor. Example of use with |system()|: >
5125 :call system("chmod +w -- " . shellescape(expand("%")))
5128 simplify({filename}) *simplify()*
5129 Simplify the file name as much as possible without changing
5130 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
5131 Unix) are not resolved. If the first path component in
5132 {filename} designates the current directory, this will be
5133 valid for the result as well. A trailing path separator is
5134 not removed either.
5135 Example: >
5136 simplify("./dir/.././/file/") == "./file/"
5137 < Note: The combination "dir/.." is only removed if "dir" is
5138 a searchable directory or does not exist. On Unix, it is also
5139 removed when "dir" is a symbolic link within the same
5140 directory. In order to resolve all the involved symbolic
5141 links before simplifying the path name, use |resolve()|.
5144 sin({expr}) *sin()*
5145 Return the sine of {expr}, measured in radians, as a |Float|.
5146 {expr} must evaluate to a |Float| or a |Number|.
5147 Examples: >
5148 :echo sin(100)
5149 < -0.506366 >
5150 :echo sin(-4.01)
5151 < 0.763301
5152 {only available when compiled with the |+float| feature}
5155 sinh({expr}) *sinh()*
5156 Return the hyperbolic sine of {expr} as a|Float|in [-inf,inf].
5157 {expr} must evaluate to a|Float|or a|Number|.
5158 Examples: >
5159 :echo sinh(0.5)
5160 < 0.521095 >
5161 :echo sinh(-0.9)
5162 < -1.026517
5163 {only available when compiled with|+float|and extention}
5166 sort({list} [, {func}]) *sort()* *E702*
5167 Sort the items in {list} in-place. Returns {list}. If you
5168 want a list to remain unmodified make a copy first: >
5169 :let sortedlist = sort(copy(mylist))
5170 < Uses the string representation of each item to sort on.
5171 Numbers sort after Strings, |Lists| after Numbers.
5172 For sorting text in the current buffer use |:sort|.
5173 When {func} is given and it is one then case is ignored.
5174 When {func} is a |Funcref| or a function name, this function
5175 is called to compare items. The function is invoked with two
5176 items as argument and must return zero if they are equal, 1 or
5177 bigger if the first one sorts after the second one, -1 or
5178 smaller if the first one sorts before the second one.
5179 Example: >
5180 func MyCompare(i1, i2)
5181 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
5182 endfunc
5183 let sortedlist = sort(mylist, "MyCompare")
5184 < A shorter compare version for this specific simple case, which
5185 ignores overflow: >
5186 func MyCompare(i1, i2)
5187 return a:i1 - a:i2
5188 endfunc
5189 <
5190 *soundfold()*
5191 soundfold({word})
5192 Return the sound-folded equivalent of {word}. Uses the first
5193 language in 'spelllang' for the current window that supports
5194 soundfolding. 'spell' must be set. When no sound folding is
5195 possible the {word} is returned unmodified.
5196 This can be used for making spelling suggestions. Note that
5197 the method can be quite slow.
5199 *spellbadword()*
5200 spellbadword([{sentence}])
5201 Without argument: The result is the badly spelled word under
5202 or after the cursor. The cursor is moved to the start of the
5203 bad word. When no bad word is found in the cursor line the
5204 result is an empty string and the cursor doesn't move.
5206 With argument: The result is the first word in {sentence} that
5207 is badly spelled. If there are no spelling mistakes the
5208 result is an empty string.
5210 The return value is a list with two items:
5211 - The badly spelled word or an empty string.
5212 - The type of the spelling error:
5213 "bad" spelling mistake
5214 "rare" rare word
5215 "local" word only valid in another region
5216 "caps" word should start with Capital
5217 Example: >
5218 echo spellbadword("the quik brown fox")
5219 < ['quik', 'bad'] ~
5221 The spelling information for the current window is used. The
5222 'spell' option must be set and the value of 'spelllang' is
5223 used.
5225 *spellsuggest()*
5226 spellsuggest({word} [, {max} [, {capital}]])
5227 Return a |List| with spelling suggestions to replace {word}.
5228 When {max} is given up to this number of suggestions are
5229 returned. Otherwise up to 25 suggestions are returned.
5231 When the {capital} argument is given and it's non-zero only
5232 suggestions with a leading capital will be given. Use this
5233 after a match with 'spellcapcheck'.
5235 {word} can be a badly spelled word followed by other text.
5236 This allows for joining two words that were split. The
5237 suggestions also include the following text, thus you can
5238 replace a line.
5240 {word} may also be a good word. Similar words will then be
5241 returned. {word} itself is not included in the suggestions,
5242 although it may appear capitalized.
5244 The spelling information for the current window is used. The
5245 'spell' option must be set and the values of 'spelllang' and
5246 'spellsuggest' are used.
5249 split({expr} [, {pattern} [, {keepempty}]]) *split()*
5250 Make a |List| out of {expr}. When {pattern} is omitted or
5251 empty each white-separated sequence of characters becomes an
5252 item.
5253 Otherwise the string is split where {pattern} matches,
5254 removing the matched characters.
5255 When the first or last item is empty it is omitted, unless the
5256 {keepempty} argument is given and it's non-zero.
5257 Other empty items are kept when {pattern} matches at least one
5258 character or when {keepempty} is non-zero.
5259 Example: >
5260 :let words = split(getline('.'), '\W\+')
5261 < To split a string in individual characters: >
5262 :for c in split(mystring, '\zs')
5263 < If you want to keep the separator you can also use '\zs': >
5264 :echo split('abc:def:ghi', ':\zs')
5265 < ['abc:', 'def:', 'ghi'] ~
5266 Splitting a table where the first element can be empty: >
5267 :let items = split(line, ':', 1)
5268 < The opposite function is |join()|.
5271 sqrt({expr}) *sqrt()*
5272 Return the non-negative square root of Float {expr} as a
5273 |Float|.
5274 {expr} must evaluate to a |Float| or a |Number|. When {expr}
5275 is negative the result is NaN (Not a Number).
5276 Examples: >
5277 :echo sqrt(100)
5278 < 10.0 >
5279 :echo sqrt(-4.01)
5280 < nan
5281 "nan" may be different, it depends on system libraries.
5282 {only available when compiled with the |+float| feature}
5285 str2float( {expr}) *str2float()*
5286 Convert String {expr} to a Float. This mostly works the same
5287 as when using a floating point number in an expression, see
5288 |floating-point-format|. But it's a bit more permissive.
5289 E.g., "1e40" is accepted, while in an expression you need to
5290 write "1.0e40".
5291 Text after the number is silently ignored.
5292 The decimal point is always '.', no matter what the locale is
5293 set to. A comma ends the number: "12,345.67" is converted to
5294 12.0. You can strip out thousands separators with
5295 |substitute()|: >
5296 let f = str2float(substitute(text, ',', '', 'g'))
5297 < {only available when compiled with the |+float| feature}
5300 str2nr( {expr} [, {base}]) *str2nr()*
5301 Convert string {expr} to a number.
5302 {base} is the conversion base, it can be 8, 10 or 16.
5303 When {base} is omitted base 10 is used. This also means that
5304 a leading zero doesn't cause octal conversion to be used, as
5305 with the default String to Number conversion.
5306 When {base} is 16 a leading "0x" or "0X" is ignored. With a
5307 different base the result will be zero.
5308 Text after the number is silently ignored.
5311 strftime({format} [, {time}]) *strftime()*
5312 The result is a String, which is a formatted date and time, as
5313 specified by the {format} string. The given {time} is used,
5314 or the current time if no time is given. The accepted
5315 {format} depends on your system, thus this is not portable!
5316 See the manual page of the C function strftime() for the
5317 format. The maximum length of the result is 80 characters.
5318 See also |localtime()| and |getftime()|.
5319 The language can be changed with the |:language| command.
5320 Examples: >
5321 :echo strftime("%c") Sun Apr 27 11:49:23 1997
5322 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
5323 :echo strftime("%y%m%d %T") 970427 11:53:55
5324 :echo strftime("%H:%M") 11:55
5325 :echo strftime("%c", getftime("file.c"))
5326 Show mod time of file.c.
5327 < Not available on all systems. To check use: >
5328 :if exists("*strftime")
5330 stridx({haystack}, {needle} [, {start}]) *stridx()*
5331 The result is a Number, which gives the byte index in
5332 {haystack} of the first occurrence of the String {needle}.
5333 If {start} is specified, the search starts at index {start}.
5334 This can be used to find a second match: >
5335 :let comma1 = stridx(line, ",")
5336 :let comma2 = stridx(line, ",", comma1 + 1)
5337 < The search is done case-sensitive.
5338 For pattern searches use |match()|.
5339 -1 is returned if the {needle} does not occur in {haystack}.
5340 See also |strridx()|.
5341 Examples: >
5342 :echo stridx("An Example", "Example") 3
5343 :echo stridx("Starting point", "Start") 0
5344 :echo stridx("Starting point", "start") -1
5345 < *strstr()* *strchr()*
5346 stridx() works similar to the C function strstr(). When used
5347 with a single character it works similar to strchr().
5349 *string()*
5350 string({expr}) Return {expr} converted to a String. If {expr} is a Number,
5351 Float, String or a composition of them, then the result can be
5352 parsed back with |eval()|.
5353 {expr} type result ~
5354 String 'string'
5355 Number 123
5356 Float 123.123456 or 1.123456e8
5357 Funcref function('name')
5358 List [item, item]
5359 Dictionary {key: value, key: value}
5360 Note that in String values the ' character is doubled.
5361 Also see |strtrans()|.
5363 *strlen()*
5364 strlen({expr}) The result is a Number, which is the length of the String
5365 {expr} in bytes.
5366 If you want to count the number of multi-byte characters (not
5367 counting composing characters) use something like this: >
5369 :let len = strlen(substitute(str, ".", "x", "g"))
5370 <
5371 If the argument is a Number it is first converted to a String.
5372 For other types an error is given.
5373 Also see |len()|.
5375 strpart({src}, {start}[, {len}]) *strpart()*
5376 The result is a String, which is part of {src}, starting from
5377 byte {start}, with the byte length {len}.
5378 When non-existing bytes are included, this doesn't result in
5379 an error, the bytes are simply omitted.
5380 If {len} is missing, the copy continues from {start} till the
5381 end of the {src}. >
5382 strpart("abcdefg", 3, 2) == "de"
5383 strpart("abcdefg", -2, 4) == "ab"
5384 strpart("abcdefg", 5, 4) == "fg"
5385 strpart("abcdefg", 3) == "defg"
5386 < Note: To get the first character, {start} must be 0. For
5387 example, to get three bytes under and after the cursor: >
5388 strpart(getline("."), col(".") - 1, 3)
5389 <
5390 strridx({haystack}, {needle} [, {start}]) *strridx()*
5391 The result is a Number, which gives the byte index in
5392 {haystack} of the last occurrence of the String {needle}.
5393 When {start} is specified, matches beyond this index are
5394 ignored. This can be used to find a match before a previous
5395 match: >
5396 :let lastcomma = strridx(line, ",")
5397 :let comma2 = strridx(line, ",", lastcomma - 1)
5398 < The search is done case-sensitive.
5399 For pattern searches use |match()|.
5400 -1 is returned if the {needle} does not occur in {haystack}.
5401 If the {needle} is empty the length of {haystack} is returned.
5402 See also |stridx()|. Examples: >
5403 :echo strridx("an angry armadillo", "an") 3
5404 < *strrchr()*
5405 When used with a single character it works similar to the C
5406 function strrchr().
5408 strtrans({expr}) *strtrans()*
5409 The result is a String, which is {expr} with all unprintable
5410 characters translated into printable characters |'isprint'|.
5411 Like they are shown in a window. Example: >
5412 echo strtrans(@a)
5413 < This displays a newline in register a as "^@" instead of
5414 starting a new line.
5416 submatch({nr}) *submatch()*
5417 Only for an expression in a |:substitute| command. Returns
5418 the {nr}'th submatch of the matched text. When {nr} is 0
5419 the whole matched text is returned.
5420 Example: >
5421 :s/\d\+/\=submatch(0) + 1/
5422 < This finds the first number in the line and adds one to it.
5423 A line break is included as a newline character.
5425 substitute({expr}, {pat}, {sub}, {flags}) *substitute()*
5426 The result is a String, which is a copy of {expr}, in which
5427 the first match of {pat} is replaced with {sub}. This works
5428 like the ":substitute" command (without any flags). But the
5429 matching with {pat} is always done like the 'magic' option is
5430 set and 'cpoptions' is empty (to make scripts portable).
5431 'ignorecase' is still relevant. 'smartcase' is not used.
5432 See |string-match| for how {pat} is used.
5433 And a "~" in {sub} is not replaced with the previous {sub}.
5434 Note that some codes in {sub} have a special meaning
5435 |sub-replace-special|. For example, to replace something with
5436 "\n" (two characters), use "\\\\n" or '\\n'.
5437 When {pat} does not match in {expr}, {expr} is returned
5438 unmodified.
5439 When {flags} is "g", all matches of {pat} in {expr} are
5440 replaced. Otherwise {flags} should be "".
5441 Example: >
5442 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
5443 < This removes the last component of the 'path' option. >
5444 :echo substitute("testing", ".*", "\\U\\0", "")
5445 < results in "TESTING".
5447 synID({lnum}, {col}, {trans}) *synID()*
5448 The result is a Number, which is the syntax ID at the position
5449 {lnum} and {col} in the current window.
5450 The syntax ID can be used with |synIDattr()| and
5451 |synIDtrans()| to obtain syntax information about text.
5453 {col} is 1 for the leftmost column, {lnum} is 1 for the first
5454 line. 'synmaxcol' applies, in a longer line zero is returned.
5456 When {trans} is non-zero, transparent items are reduced to the
5457 item that they reveal. This is useful when wanting to know
5458 the effective color. When {trans} is zero, the transparent
5459 item is returned. This is useful when wanting to know which
5460 syntax item is effective (e.g. inside parens).
5461 Warning: This function can be very slow. Best speed is
5462 obtained by going through the file in forward direction.
5464 Example (echoes the name of the syntax item under the cursor): >
5465 :echo synIDattr(synID(line("."), col("."), 1), "name")
5466 <
5467 synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
5468 The result is a String, which is the {what} attribute of
5469 syntax ID {synID}. This can be used to obtain information
5470 about a syntax item.
5471 {mode} can be "gui", "cterm" or "term", to get the attributes
5472 for that mode. When {mode} is omitted, or an invalid value is
5473 used, the attributes for the currently active highlighting are
5474 used (GUI, cterm or term).
5475 Use synIDtrans() to follow linked highlight groups.
5476 {what} result
5477 "name" the name of the syntax item
5478 "fg" foreground color (GUI: color name used to set
5479 the color, cterm: color number as a string,
5480 term: empty string)
5481 "bg" background color (as with "fg")
5482 "font" font name (only available in the GUI)
5483 |highlight-font|
5484 "sp" special color (as with "fg") |highlight-guisp|
5485 "fg#" like "fg", but for the GUI and the GUI is
5486 running the name in "#RRGGBB" form
5487 "bg#" like "fg#" for "bg"
5488 "sp#" like "fg#" for "sp"
5489 "bold" "1" if bold
5490 "italic" "1" if italic
5491 "reverse" "1" if reverse
5492 "inverse" "1" if inverse (= reverse)
5493 "standout" "1" if standout
5494 "underline" "1" if underlined
5495 "undercurl" "1" if undercurled
5497 Example (echoes the color of the syntax item under the
5498 cursor): >
5499 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
5500 <
5501 synIDtrans({synID}) *synIDtrans()*
5502 The result is a Number, which is the translated syntax ID of
5503 {synID}. This is the syntax group ID of what is being used to
5504 highlight the character. Highlight links given with
5505 ":highlight link" are followed.
5507 synstack({lnum}, {col}) *synstack()*
5508 Return a |List|, which is the stack of syntax items at the
5509 position {lnum} and {col} in the current window. Each item in
5510 the List is an ID like what |synID()| returns.
5511 The first item in the List is the outer region, following are
5512 items contained in that one. The last one is what |synID()|
5513 returns, unless not the whole item is highlighted or it is a
5514 transparent item.
5515 This function is useful for debugging a syntax file.
5516 Example that shows the syntax stack under the cursor: >
5517 for id in synstack(line("."), col("."))
5518 echo synIDattr(id, "name")
5519 endfor
5521 system({expr} [, {input}]) *system()* *E677*
5522 Get the output of the shell command {expr}.
5523 When {input} is given, this string is written to a file and
5524 passed as stdin to the command. The string is written as-is,
5525 you need to take care of using the correct line separators
5526 yourself. Pipes are not used.
5527 Note: Use |shellescape()| to escape special characters in a
5528 command argument. Newlines in {expr} may cause the command to
5529 fail. The characters in 'shellquote' and 'shellxquote' may
5530 also cause trouble.
5531 This is not to be used for interactive commands.
5533 The result is a String. Example: >
5534 :let files = system("ls " . shellescape(expand('%:h')))
5536 < To make the result more system-independent, the shell output
5537 is filtered to replace <CR> with <NL> for Macintosh, and
5538 <CR><NL> with <NL> for DOS-like systems.
5539 The command executed is constructed using several options:
5540 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
5541 ({tmp} is an automatically generated file name).
5542 For Unix and OS/2 braces are put around {expr} to allow for
5543 concatenated commands.
5545 The command will be executed in "cooked" mode, so that a
5546 CTRL-C will interrupt the command (on Unix at least).
5548 The resulting error code can be found in |v:shell_error|.
5549 This function will fail in |restricted-mode|.
5551 Note that any wrong value in the options mentioned above may
5552 make the function fail. It has also been reported to fail
5553 when using a security agent application.
5554 Unlike ":!cmd" there is no automatic check for changed files.
5555 Use |:checktime| to force a check.
5558 tabpagebuflist([{arg}]) *tabpagebuflist()*
5559 The result is a |List|, where each item is the number of the
5560 buffer associated with each window in the current tab page.
5561 {arg} specifies the number of tab page to be used. When
5562 omitted the current tab page is used.
5563 When {arg} is invalid the number zero is returned.
5564 To get a list of all buffers in all tabs use this: >
5565 tablist = []
5566 for i in range(tabpagenr('$'))
5567 call extend(tablist, tabpagebuflist(i + 1))
5568 endfor
5569 < Note that a buffer may appear in more than one window.
5572 tabpagenr([{arg}]) *tabpagenr()*
5573 The result is a Number, which is the number of the current
5574 tab page. The first tab page has number 1.
5575 When the optional argument is "$", the number of the last tab
5576 page is returned (the tab page count).
5577 The number can be used with the |:tab| command.
5580 tabpagewinnr({tabarg}, [{arg}]) *tabpagewinnr()*
5581 Like |winnr()| but for tab page {arg}.
5582 {tabarg} specifies the number of tab page to be used.
5583 {arg} is used like with |winnr()|:
5584 - When omitted the current window number is returned. This is
5585 the window which will be used when going to this tab page.
5586 - When "$" the number of windows is returned.
5587 - When "#" the previous window nr is returned.
5588 Useful examples: >
5589 tabpagewinnr(1) " current window of tab page 1
5590 tabpagewinnr(4, '$') " number of windows in tab page 4
5591 < When {tabarg} is invalid zero is returned.
5593 *tagfiles()*
5594 tagfiles() Returns a |List| with the file names used to search for tags
5595 for the current buffer. This is the 'tags' option expanded.
5598 taglist({expr}) *taglist()*
5599 Returns a list of tags matching the regular expression {expr}.
5600 Each list item is a dictionary with at least the following
5601 entries:
5602 name Name of the tag.
5603 filename Name of the file where the tag is
5604 defined. It is either relative to the
5605 current directory or a full path.
5606 cmd Ex command used to locate the tag in
5607 the file.
5608 kind Type of the tag. The value for this
5609 entry depends on the language specific
5610 kind values. Only available when
5611 using a tags file generated by
5612 Exuberant ctags or hdrtag.
5613 static A file specific tag. Refer to
5614 |static-tag| for more information.
5615 More entries may be present, depending on the content of the
5616 tags file: access, implementation, inherits and signature.
5617 Refer to the ctags documentation for information about these
5618 fields. For C code the fields "struct", "class" and "enum"
5619 may appear, they give the name of the entity the tag is
5620 contained in.
5622 The ex-command 'cmd' can be either an ex search pattern, a
5623 line number or a line number followed by a byte number.
5625 If there are no matching tags, then an empty list is returned.
5627 To get an exact tag match, the anchors '^' and '$' should be
5628 used in {expr}. Refer to |tag-regexp| for more information
5629 about the tag search regular expression pattern.
5631 Refer to |'tags'| for information about how the tags file is
5632 located by Vim. Refer to |tags-file-format| for the format of
5633 the tags file generated by the different ctags tools.
5635 tan({expr}) *tan()*
5636 Return the tangent of {expr}, measured in radians, as a|Float|
5637 in the range [-inf,inf].
5638 {expr} must evaluate to a|Float|or a|Number|.
5639 Examples: >
5640 :echo tan(10)
5641 < 0.648361 >
5642 :echo tan(-4.01)
5643 < -1.181502
5644 {only available when compiled with|+float|and extention}
5647 tanh({expr}) *tanh()*
5648 Return the hyperbolic tangent of {expr} as a|Float|in [-1,1].
5649 {expr} must evaluate to a|Float|or a|Number|.
5650 Examples: >
5651 :echo tanh(0.5)
5652 < 0.462117 >
5653 :echo tanh(-1)
5654 < -0.761594
5655 {only available when compiled with|+float|and extention}
5657 tempname() *tempname()* *temp-file-name*
5658 The result is a String, which is the name of a file that
5659 doesn't exist. It can be used for a temporary file. The name
5660 is different for at least 26 consecutive calls. Example: >
5661 :let tmpfile = tempname()
5662 :exe "redir > " . tmpfile
5663 < For Unix, the file will be in a private directory |tempfile|.
5664 For MS-Windows forward slashes are used when the 'shellslash'
5665 option is set or when 'shellcmdflag' starts with '-'.
5667 tolower({expr}) *tolower()*
5668 The result is a copy of the String given, with all uppercase
5669 characters turned into lowercase (just like applying |gu| to
5670 the string).
5672 toupper({expr}) *toupper()*
5673 The result is a copy of the String given, with all lowercase
5674 characters turned into uppercase (just like applying |gU| to
5675 the string).
5677 tr({src}, {fromstr}, {tostr}) *tr()*
5678 The result is a copy of the {src} string with all characters
5679 which appear in {fromstr} replaced by the character in that
5680 position in the {tostr} string. Thus the first character in
5681 {fromstr} is translated into the first character in {tostr}
5682 and so on. Exactly like the unix "tr" command.
5683 This code also deals with multibyte characters properly.
5685 Examples: >
5686 echo tr("hello there", "ht", "HT")
5687 < returns "Hello THere" >
5688 echo tr("<blob>", "<>", "{}")
5689 < returns "{blob}"
5691 trunc({expr}) *trunc()*
5692 Return the largest integral value with magnitude less than or
5693 equal to {expr} as a |Float| (truncate towards zero).
5694 {expr} must evaluate to a |Float| or a |Number|.
5695 Examples: >
5696 echo trunc(1.456)
5697 < 1.0 >
5698 echo trunc(-5.456)
5699 < -5.0 >
5700 echo trunc(4.0)
5701 < 4.0
5702 {only available when compiled with the |+float| feature}
5704 *type()*
5705 type({expr}) The result is a Number, depending on the type of {expr}:
5706 Number: 0
5707 String: 1
5708 Funcref: 2
5709 List: 3
5710 Dictionary: 4
5711 Float: 5
5712 To avoid the magic numbers it should be used this way: >
5713 :if type(myvar) == type(0)
5714 :if type(myvar) == type("")
5715 :if type(myvar) == type(function("tr"))
5716 :if type(myvar) == type([])
5717 :if type(myvar) == type({})
5718 :if type(myvar) == type(0.0)
5720 values({dict}) *values()*
5721 Return a |List| with all the values of {dict}. The |List| is
5722 in arbitrary order.
5725 virtcol({expr}) *virtcol()*
5726 The result is a Number, which is the screen column of the file
5727 position given with {expr}. That is, the last screen position
5728 occupied by the character at that position, when the screen
5729 would be of unlimited width. When there is a <Tab> at the
5730 position, the returned Number will be the column at the end of
5731 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
5732 set to 8, it returns 8.
5733 For the byte position use |col()|.
5734 For the use of {expr} see |col()|.
5735 When 'virtualedit' is used {expr} can be [lnum, col, off], where
5736 "off" is the offset in screen columns from the start of the
5737 character. E.g., a position within a <Tab> or after the last
5738 character.
5739 When Virtual editing is active in the current mode, a position
5740 beyond the end of the line can be returned. |'virtualedit'|
5741 The accepted positions are:
5742 . the cursor position
5743 $ the end of the cursor line (the result is the
5744 number of displayed characters in the cursor line
5745 plus one)
5746 'x position of mark x (if the mark is not set, 0 is
5747 returned)
5748 Note that only marks in the current file can be used.
5749 Examples: >
5750 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
5751 virtcol("$") with text "foo^Lbar", returns 9
5752 virtcol("'t") with text " there", with 't at 'h', returns 6
5753 < The first column is 1. 0 is returned for an error.
5754 A more advanced example that echoes the maximum length of
5755 all lines: >
5756 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
5759 visualmode([expr]) *visualmode()*
5760 The result is a String, which describes the last Visual mode
5761 used in the current buffer. Initially it returns an empty
5762 string, but once Visual mode has been used, it returns "v",
5763 "V", or "<CTRL-V>" (a single CTRL-V character) for
5764 character-wise, line-wise, or block-wise Visual mode
5765 respectively.
5766 Example: >
5767 :exe "normal " . visualmode()
5768 < This enters the same Visual mode as before. It is also useful
5769 in scripts if you wish to act differently depending on the
5770 Visual mode that was used.
5771 If Visual mode is active, use |mode()| to get the Visual mode
5772 (e.g., in a |:vmap|).
5773 *non-zero-arg*
5774 If [expr] is supplied and it evaluates to a non-zero Number or
5775 a non-empty String, then the Visual mode will be cleared and
5776 the old value is returned. Note that " " and "0" are also
5777 non-empty strings, thus cause the mode to be cleared. A List,
5778 Dictionary or Float is not a Number or String, thus does not
5779 cause the mode to be cleared.
5781 *winbufnr()*
5782 winbufnr({nr}) The result is a Number, which is the number of the buffer
5783 associated with window {nr}. When {nr} is zero, the number of
5784 the buffer in the current window is returned. When window
5785 {nr} doesn't exist, -1 is returned.
5786 Example: >
5787 :echo "The file in the current window is " . bufname(winbufnr(0))
5788 <
5789 *wincol()*
5790 wincol() The result is a Number, which is the virtual column of the
5791 cursor in the window. This is counting screen cells from the
5792 left side of the window. The leftmost column is one.
5794 winheight({nr}) *winheight()*
5795 The result is a Number, which is the height of window {nr}.
5796 When {nr} is zero, the height of the current window is
5797 returned. When window {nr} doesn't exist, -1 is returned.
5798 An existing window always has a height of zero or more.
5799 Examples: >
5800 :echo "The current window has " . winheight(0) . " lines."
5801 <
5802 *winline()*
5803 winline() The result is a Number, which is the screen line of the cursor
5804 in the window. This is counting screen lines from the top of
5805 the window. The first line is one.
5806 If the cursor was moved the view on the file will be updated
5807 first, this may cause a scroll.
5809 *winnr()*
5810 winnr([{arg}]) The result is a Number, which is the number of the current
5811 window. The top window has number 1.
5812 When the optional argument is "$", the number of the
5813 last window is returned (the window count).
5814 When the optional argument is "#", the number of the last
5815 accessed window is returned (where |CTRL-W_p| goes to).
5816 If there is no previous window or it is in another tab page 0
5817 is returned.
5818 The number can be used with |CTRL-W_w| and ":wincmd w"
5819 |:wincmd|.
5820 Also see |tabpagewinnr()|.
5822 *winrestcmd()*
5823 winrestcmd() Returns a sequence of |:resize| commands that should restore
5824 the current window sizes. Only works properly when no windows
5825 are opened or closed and the current window and tab page is
5826 unchanged.
5827 Example: >
5828 :let cmd = winrestcmd()
5829 :call MessWithWindowSizes()
5830 :exe cmd
5831 <
5832 *winrestview()*
5833 winrestview({dict})
5834 Uses the |Dictionary| returned by |winsaveview()| to restore
5835 the view of the current window.
5836 If you have changed the values the result is unpredictable.
5837 If the window size changed the result won't be the same.
5839 *winsaveview()*
5840 winsaveview() Returns a |Dictionary| that contains information to restore
5841 the view of the current window. Use |winrestview()| to
5842 restore the view.
5843 This is useful if you have a mapping that jumps around in the
5844 buffer and you want to go back to the original view.
5845 This does not save fold information. Use the 'foldenable'
5846 option to temporarily switch off folding, so that folds are
5847 not opened when moving around.
5848 The return value includes:
5849 lnum cursor line number
5850 col cursor column
5851 coladd cursor column offset for 'virtualedit'
5852 curswant column for vertical movement
5853 topline first line in the window
5854 topfill filler lines, only in diff mode
5855 leftcol first column displayed
5856 skipcol columns skipped
5857 Note that no option values are saved.
5860 winwidth({nr}) *winwidth()*
5861 The result is a Number, which is the width of window {nr}.
5862 When {nr} is zero, the width of the current window is
5863 returned. When window {nr} doesn't exist, -1 is returned.
5864 An existing window always has a width of zero or more.
5865 Examples: >
5866 :echo "The current window has " . winwidth(0) . " columns."
5867 :if winwidth(0) <= 50
5868 : exe "normal 50\<C-W>|"
5869 :endif
5870 <
5871 *writefile()*
5872 writefile({list}, {fname} [, {binary}])
5873 Write |List| {list} to file {fname}. Each list item is
5874 separated with a NL. Each list item must be a String or
5875 Number.
5876 When {binary} is equal to "b" binary mode is used: There will
5877 not be a NL after the last list item. An empty item at the
5878 end does cause the last line in the file to end in a NL.
5879 All NL characters are replaced with a NUL character.
5880 Inserting CR characters needs to be done before passing {list}
5881 to writefile().
5882 An existing file is overwritten, if possible.
5883 When the write fails -1 is returned, otherwise 0. There is an
5884 error message if the file can't be created or when writing
5885 fails.
5886 Also see |readfile()|.
5887 To copy a file byte for byte: >
5888 :let fl = readfile("foo", "b")
5889 :call writefile(fl, "foocopy", "b")
5890 <
5892 *feature-list*
5893 There are three types of features:
5894 1. Features that are only supported when they have been enabled when Vim
5895 was compiled |+feature-list|. Example: >
5896 :if has("cindent")
5897 2. Features that are only supported when certain conditions have been met.
5898 Example: >
5899 :if has("gui_running")
5900 < *has-patch*
5901 3. Included patches. First check |v:version| for the version of Vim.
5902 Then the "patch123" feature means that patch 123 has been included for
5903 this version. Example (checking version 6.2.148 or later): >
5904 :if v:version > 602 || v:version == 602 && has("patch148")
5905 < Note that it's possible for patch 147 to be omitted even though 148 is
5906 included.
5908 all_builtin_terms Compiled with all builtin terminals enabled.
5909 amiga Amiga version of Vim.
5910 arabic Compiled with Arabic support |Arabic|.
5911 arp Compiled with ARP support (Amiga).
5912 autocmd Compiled with autocommand support. |autocommand|
5913 balloon_eval Compiled with |balloon-eval| support.
5914 balloon_multiline GUI supports multiline balloons.
5915 beos BeOS version of Vim.
5916 browse Compiled with |:browse| support, and browse() will
5917 work.
5918 builtin_terms Compiled with some builtin terminals.
5919 byte_offset Compiled with support for 'o' in 'statusline'
5920 cindent Compiled with 'cindent' support.
5921 clientserver Compiled with remote invocation support |clientserver|.
5922 clipboard Compiled with 'clipboard' support.
5923 cmdline_compl Compiled with |cmdline-completion| support.
5924 cmdline_hist Compiled with |cmdline-history| support.
5925 cmdline_info Compiled with 'showcmd' and 'ruler' support.
5926 comments Compiled with |'comments'| support.
5927 cryptv Compiled with encryption support |encryption|.
5928 cscope Compiled with |cscope| support.
5929 compatible Compiled to be very Vi compatible.
5930 debug Compiled with "DEBUG" defined.
5931 dialog_con Compiled with console dialog support.
5932 dialog_gui Compiled with GUI dialog support.
5933 diff Compiled with |vimdiff| and 'diff' support.
5934 digraphs Compiled with support for digraphs.
5935 dnd Compiled with support for the "~ register |quote_~|.
5936 dos32 32 bits DOS (DJGPP) version of Vim.
5937 dos16 16 bits DOS version of Vim.
5938 ebcdic Compiled on a machine with ebcdic character set.
5939 emacs_tags Compiled with support for Emacs tags.
5940 eval Compiled with expression evaluation support. Always
5941 true, of course!
5942 ex_extra Compiled with extra Ex commands |+ex_extra|.
5943 extra_search Compiled with support for |'incsearch'| and
5944 |'hlsearch'|
5945 farsi Compiled with Farsi support |farsi|.
5946 file_in_path Compiled with support for |gf| and |<cfile>|
5947 filterpipe When 'shelltemp' is off pipes are used for shell
5948 read/write/filter commands
5949 find_in_path Compiled with support for include file searches
5950 |+find_in_path|.
5951 float Compiled with support for |Float|.
5952 fname_case Case in file names matters (for Amiga, MS-DOS, and
5953 Windows this is not present).
5954 folding Compiled with |folding| support.
5955 footer Compiled with GUI footer support. |gui-footer|
5956 fork Compiled to use fork()/exec() instead of system().
5957 gettext Compiled with message translation |multi-lang|
5958 gui Compiled with GUI enabled.
5959 gui_athena Compiled with Athena GUI.
5960 gui_gtk Compiled with GTK+ GUI (any version).
5961 gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
5962 gui_gnome Compiled with Gnome support (gui_gtk is also defined).
5963 gui_mac Compiled with Macintosh GUI.
5964 gui_motif Compiled with Motif GUI.
5965 gui_photon Compiled with Photon GUI.
5966 gui_win32 Compiled with MS Windows Win32 GUI.
5967 gui_win32s idem, and Win32s system being used (Windows 3.1)
5968 gui_running Vim is running in the GUI, or it will start soon.
5969 hangul_input Compiled with Hangul input support. |hangul|
5970 iconv Can use iconv() for conversion.
5971 insert_expand Compiled with support for CTRL-X expansion commands in
5972 Insert mode.
5973 jumplist Compiled with |jumplist| support.
5974 keymap Compiled with 'keymap' support.
5975 langmap Compiled with 'langmap' support.
5976 libcall Compiled with |libcall()| support.
5977 linebreak Compiled with 'linebreak', 'breakat' and 'showbreak'
5978 support.
5979 lispindent Compiled with support for lisp indenting.
5980 listcmds Compiled with commands for the buffer list |:files|
5981 and the argument list |arglist|.
5982 localmap Compiled with local mappings and abbr. |:map-local|
5983 mac Macintosh version of Vim.
5984 macunix Macintosh version of Vim, using Unix files (OS-X).
5985 menu Compiled with support for |:menu|.
5986 mksession Compiled with support for |:mksession|.
5987 modify_fname Compiled with file name modifiers. |filename-modifiers|
5988 mouse Compiled with support mouse.
5989 mouseshape Compiled with support for 'mouseshape'.
5990 mouse_dec Compiled with support for Dec terminal mouse.
5991 mouse_gpm Compiled with support for gpm (Linux console mouse)
5992 mouse_netterm Compiled with support for netterm mouse.
5993 mouse_pterm Compiled with support for qnx pterm mouse.
5994 mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
5995 mouse_xterm Compiled with support for xterm mouse.
5996 multi_byte Compiled with support for 'encoding'
5997 multi_byte_encoding 'encoding' is set to a multi-byte encoding.
5998 multi_byte_ime Compiled with support for IME input method.
5999 multi_lang Compiled with support for multiple languages.
6000 mzscheme Compiled with MzScheme interface |mzscheme|.
6001 netbeans_intg Compiled with support for |netbeans|.
6002 netbeans_enabled Compiled with support for |netbeans| and it's used.
6003 ole Compiled with OLE automation support for Win32.
6004 os2 OS/2 version of Vim.
6005 osfiletype Compiled with support for osfiletypes |+osfiletype|
6006 path_extra Compiled with up/downwards search in 'path' and 'tags'
6007 perl Compiled with Perl interface.
6008 postscript Compiled with PostScript file printing.
6009 printer Compiled with |:hardcopy| support.
6010 profile Compiled with |:profile| support.
6011 python Compiled with Python interface.
6012 qnx QNX version of Vim.
6013 quickfix Compiled with |quickfix| support.
6014 reltime Compiled with |reltime()| support.
6015 rightleft Compiled with 'rightleft' support.
6016 ruby Compiled with Ruby interface |ruby|.
6017 scrollbind Compiled with 'scrollbind' support.
6018 showcmd Compiled with 'showcmd' support.
6019 signs Compiled with |:sign| support.
6020 smartindent Compiled with 'smartindent' support.
6021 sniff Compiled with SNiFF interface support.
6022 startuptime Compiled with |--startuptime| support.
6023 statusline Compiled with support for 'statusline', 'rulerformat'
6024 and special formats of 'titlestring' and 'iconstring'.
6025 sun_workshop Compiled with support for Sun |workshop|.
6026 spell Compiled with spell checking support |spell|.
6027 syntax Compiled with syntax highlighting support |syntax|.
6028 syntax_items There are active syntax highlighting items for the
6029 current buffer.
6030 system Compiled to use system() instead of fork()/exec().
6031 tag_binary Compiled with binary searching in tags files
6032 |tag-binary-search|.
6033 tag_old_static Compiled with support for old static tags
6034 |tag-old-static|.
6035 tag_any_white Compiled with support for any white characters in tags
6036 files |tag-any-white|.
6037 tcl Compiled with Tcl interface.
6038 terminfo Compiled with terminfo instead of termcap.
6039 termresponse Compiled with support for |t_RV| and |v:termresponse|.
6040 textobjects Compiled with support for |text-objects|.
6041 tgetent Compiled with tgetent support, able to use a termcap
6042 or terminfo file.
6043 title Compiled with window title support |'title'|.
6044 toolbar Compiled with support for |gui-toolbar|.
6045 unix Unix version of Vim.
6046 user_commands User-defined commands.
6047 viminfo Compiled with viminfo support.
6048 vim_starting True while initial source'ing takes place.
6049 vertsplit Compiled with vertically split windows |:vsplit|.
6050 virtualedit Compiled with 'virtualedit' option.
6051 visual Compiled with Visual mode.
6052 visualextra Compiled with extra Visual mode commands.
6053 |blockwise-operators|.
6054 vms VMS version of Vim.
6055 vreplace Compiled with |gR| and |gr| commands.
6056 wildignore Compiled with 'wildignore' option.
6057 wildmenu Compiled with 'wildmenu' option.
6058 windows Compiled with support for more than one window.
6059 winaltkeys Compiled with 'winaltkeys' option.
6060 win16 Win16 version of Vim (MS-Windows 3.1).
6061 win32 Win32 version of Vim (MS-Windows 95/98/ME/NT/2000/XP).
6062 win64 Win64 version of Vim (MS-Windows 64 bit).
6063 win32unix Win32 version of Vim, using Unix files (Cygwin)
6064 win95 Win32 version for MS-Windows 95/98/ME.
6065 writebackup Compiled with 'writebackup' default on.
6066 xfontset Compiled with X fontset support |xfontset|.
6067 xim Compiled with X input method support |xim|.
6068 xsmp Compiled with X session management support.
6069 xsmp_interact Compiled with interactive X session management support.
6070 xterm_clipboard Compiled with support for xterm clipboard.
6071 xterm_save Compiled with support for saving and restoring the
6072 xterm screen.
6073 x11 Compiled with X11 support.
6075 *string-match*
6076 Matching a pattern in a String
6078 A regexp pattern as explained at |pattern| is normally used to find a match in
6079 the buffer lines. When a pattern is used to find a match in a String, almost
6080 everything works in the same way. The difference is that a String is handled
6081 like it is one line. When it contains a "\n" character, this is not seen as a
6082 line break for the pattern. It can be matched with a "\n" in the pattern, or
6083 with ".". Example: >
6084 :let a = "aaaa\nxxxx"
6085 :echo matchstr(a, "..\n..")
6086 aa
6087 xx
6088 :echo matchstr(a, "a.x")
6089 a
6090 x
6092 Don't forget that "^" will only match at the first character of the String and
6093 "$" at the last character of the string. They don't match after or before a
6094 "\n".
6096 ==============================================================================
6097 5. Defining functions *user-functions*
6099 New functions can be defined. These can be called just like builtin
6100 functions. The function executes a sequence of Ex commands. Normal mode
6101 commands can be executed with the |:normal| command.
6103 The function name must start with an uppercase letter, to avoid confusion with
6104 builtin functions. To prevent from using the same name in different scripts
6105 avoid obvious, short names. A good habit is to start the function name with
6106 the name of the script, e.g., "HTMLcolor()".
6108 It's also possible to use curly braces, see |curly-braces-names|. And the
6109 |autoload| facility is useful to define a function only when it's called.
6111 *local-function*
6112 A function local to a script must start with "s:". A local script function
6113 can only be called from within the script and from functions, user commands
6114 and autocommands defined in the script. It is also possible to call the
6115 function from a mapping defined in the script, but then |<SID>| must be used
6116 instead of "s:" when the mapping is expanded outside of the script.
6118 *:fu* *:function* *E128* *E129* *E123*
6119 :fu[nction] List all functions and their arguments.
6121 :fu[nction] {name} List function {name}.
6122 {name} can also be a |Dictionary| entry that is a
6123 |Funcref|: >
6124 :function dict.init
6126 :fu[nction] /{pattern} List functions with a name matching {pattern}.
6127 Example that lists all functions ending with "File": >
6128 :function /File$
6129 <
6130 *:function-verbose*
6131 When 'verbose' is non-zero, listing a function will also display where it was
6132 last defined. Example: >
6134 :verbose function SetFileTypeSH
6135 function SetFileTypeSH(name)
6136 Last set from /usr/share/vim/vim-7.0/filetype.vim
6137 <
6138 See |:verbose-cmd| for more information.
6140 *E124* *E125*
6141 :fu[nction][!] {name}([arguments]) [range] [abort] [dict]
6142 Define a new function by the name {name}. The name
6143 must be made of alphanumeric characters and '_', and
6144 must start with a capital or "s:" (see above).
6146 {name} can also be a |Dictionary| entry that is a
6147 |Funcref|: >
6148 :function dict.init(arg)
6149 < "dict" must be an existing dictionary. The entry
6150 "init" is added if it didn't exist yet. Otherwise [!]
6151 is required to overwrite an existing function. The
6152 result is a |Funcref| to a numbered function. The
6153 function can only be used with a |Funcref| and will be
6154 deleted if there are no more references to it.
6155 *E127* *E122*
6156 When a function by this name already exists and [!] is
6157 not used an error message is given. When [!] is used,
6158 an existing function is silently replaced. Unless it
6159 is currently being executed, that is an error.
6161 For the {arguments} see |function-argument|.
6163 *a:firstline* *a:lastline*
6164 When the [range] argument is added, the function is
6165 expected to take care of a range itself. The range is
6166 passed as "a:firstline" and "a:lastline". If [range]
6167 is excluded, ":{range}call" will call the function for
6168 each line in the range, with the cursor on the start
6169 of each line. See |function-range-example|.
6171 When the [abort] argument is added, the function will
6172 abort as soon as an error is detected.
6174 When the [dict] argument is added, the function must
6175 be invoked through an entry in a |Dictionary|. The
6176 local variable "self" will then be set to the
6177 dictionary. See |Dictionary-function|.
6179 *function-search-undo*
6180 The last used search pattern and the redo command "."
6181 will not be changed by the function. This also
6182 implies that the effect of |:nohlsearch| is undone
6183 when the function returns.
6185 *:endf* *:endfunction* *E126* *E193*
6186 :endf[unction] The end of a function definition. Must be on a line
6187 by its own, without other commands.
6189 *:delf* *:delfunction* *E130* *E131*
6190 :delf[unction] {name} Delete function {name}.
6191 {name} can also be a |Dictionary| entry that is a
6192 |Funcref|: >
6193 :delfunc dict.init
6194 < This will remove the "init" entry from "dict". The
6195 function is deleted if there are no more references to
6196 it.
6197 *:retu* *:return* *E133*
6198 :retu[rn] [expr] Return from a function. When "[expr]" is given, it is
6199 evaluated and returned as the result of the function.
6200 If "[expr]" is not given, the number 0 is returned.
6201 When a function ends without an explicit ":return",
6202 the number 0 is returned.
6203 Note that there is no check for unreachable lines,
6204 thus there is no warning if commands follow ":return".
6206 If the ":return" is used after a |:try| but before the
6207 matching |:finally| (if present), the commands
6208 following the ":finally" up to the matching |:endtry|
6209 are executed first. This process applies to all
6210 nested ":try"s inside the function. The function
6211 returns at the outermost ":endtry".
6213 *function-argument* *a:var*
6214 An argument can be defined by giving its name. In the function this can then
6215 be used as "a:name" ("a:" for argument).
6216 *a:0* *a:1* *a:000* *E740* *...*
6217 Up to 20 arguments can be given, separated by commas. After the named
6218 arguments an argument "..." can be specified, which means that more arguments
6219 may optionally be following. In the function the extra arguments can be used
6220 as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which
6221 can be 0). "a:000" is set to a |List| that contains these arguments. Note
6222 that "a:1" is the same as "a:000[0]".
6223 *E742*
6224 The a: scope and the variables in it cannot be changed, they are fixed.
6225 However, if a |List| or |Dictionary| is used, you can change their contents.
6226 Thus you can pass a |List| to a function and have the function add an item to
6227 it. If you want to make sure the function cannot change a |List| or
6228 |Dictionary| use |:lockvar|.
6230 When not using "...", the number of arguments in a function call must be equal
6231 to the number of named arguments. When using "...", the number of arguments
6232 may be larger.
6234 It is also possible to define a function without any arguments. You must
6235 still supply the () then. The body of the function follows in the next lines,
6236 until the matching |:endfunction|. It is allowed to define another function
6237 inside a function body.
6239 *local-variables*
6240 Inside a function variables can be used. These are local variables, which
6241 will disappear when the function returns. Global variables need to be
6242 accessed with "g:".
6244 Example: >
6245 :function Table(title, ...)
6246 : echohl Title
6247 : echo a:title
6248 : echohl None
6249 : echo a:0 . " items:"
6250 : for s in a:000
6251 : echon ' ' . s
6252 : endfor
6253 :endfunction
6255 This function can then be called with: >
6256 call Table("Table", "line1", "line2")
6257 call Table("Empty Table")
6259 To return more than one value, return a |List|: >
6260 :function Compute(n1, n2)
6261 : if a:n2 == 0
6262 : return ["fail", 0]
6263 : endif
6264 : return ["ok", a:n1 / a:n2]
6265 :endfunction
6267 This function can then be called with: >
6268 :let [success, div] = Compute(102, 6)
6269 :if success == "ok"
6270 : echo div
6271 :endif
6272 <
6273 *:cal* *:call* *E107* *E117*
6274 :[range]cal[l] {name}([arguments])
6275 Call a function. The name of the function and its arguments
6276 are as specified with |:function|. Up to 20 arguments can be
6277 used. The returned value is discarded.
6278 Without a range and for functions that accept a range, the
6279 function is called once. When a range is given the cursor is
6280 positioned at the start of the first line before executing the
6281 function.
6282 When a range is given and the function doesn't handle it
6283 itself, the function is executed for each line in the range,
6284 with the cursor in the first column of that line. The cursor
6285 is left at the last line (possibly moved by the last function
6286 call). The arguments are re-evaluated for each line. Thus
6287 this works:
6288 *function-range-example* >
6289 :function Mynumber(arg)
6290 : echo line(".") . " " . a:arg
6291 :endfunction
6292 :1,5call Mynumber(getline("."))
6293 <
6294 The "a:firstline" and "a:lastline" are defined anyway, they
6295 can be used to do something different at the start or end of
6296 the range.
6298 Example of a function that handles the range itself: >
6300 :function Cont() range
6301 : execute (a:firstline + 1) . "," . a:lastline . 's/^/\t\\ '
6302 :endfunction
6303 :4,8call Cont()
6304 <
6305 This function inserts the continuation character "\" in front
6306 of all the lines in the range, except the first one.
6308 When the function returns a composite value it can be further
6309 dereferenced, but the range will not be used then. Example: >
6310 :4,8call GetDict().method()
6311 < Here GetDict() gets the range but method() does not.
6313 *E132*
6314 The recursiveness of user functions is restricted with the |'maxfuncdepth'|
6315 option.
6318 AUTOMATICALLY LOADING FUNCTIONS ~
6319 *autoload-functions*
6320 When using many or large functions, it's possible to automatically define them
6321 only when they are used. There are two methods: with an autocommand and with
6322 the "autoload" directory in 'runtimepath'.
6325 Using an autocommand ~
6327 This is introduced in the user manual, section |41.14|.
6329 The autocommand is useful if you have a plugin that is a long Vim script file.
6330 You can define the autocommand and quickly quit the script with |:finish|.
6331 That makes Vim startup faster. The autocommand should then load the same file
6332 again, setting a variable to skip the |:finish| command.
6334 Use the FuncUndefined autocommand event with a pattern that matches the
6335 function(s) to be defined. Example: >
6337 :au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
6339 The file "~/vim/bufnetfuncs.vim" should then define functions that start with
6340 "BufNet". Also see |FuncUndefined|.
6343 Using an autoload script ~
6344 *autoload* *E746*
6345 This is introduced in the user manual, section |41.15|.
6347 Using a script in the "autoload" directory is simpler, but requires using
6348 exactly the right file name. A function that can be autoloaded has a name
6349 like this: >
6351 :call filename#funcname()
6353 When such a function is called, and it is not defined yet, Vim will search the
6354 "autoload" directories in 'runtimepath' for a script file called
6355 "filename.vim". For example "~/.vim/autoload/filename.vim". That file should
6356 then define the function like this: >
6358 function filename#funcname()
6359 echo "Done!"
6360 endfunction
6362 The file name and the name used before the # in the function must match
6363 exactly, and the defined function must have the name exactly as it will be
6364 called.
6366 It is possible to use subdirectories. Every # in the function name works like
6367 a path separator. Thus when calling a function: >
6369 :call foo#bar#func()
6371 Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
6373 This also works when reading a variable that has not been set yet: >
6375 :let l = foo#bar#lvar
6377 However, when the autoload script was already loaded it won't be loaded again
6378 for an unknown variable.
6380 When assigning a value to such a variable nothing special happens. This can
6381 be used to pass settings to the autoload script before it's loaded: >
6383 :let foo#bar#toggle = 1
6384 :call foo#bar#func()
6386 Note that when you make a mistake and call a function that is supposed to be
6387 defined in an autoload script, but the script doesn't actually define the
6388 function, the script will be sourced every time you try to call the function.
6389 And you will get an error message every time.
6391 Also note that if you have two script files, and one calls a function in the
6392 other and vice versa, before the used function is defined, it won't work.
6393 Avoid using the autoload functionality at the toplevel.
6395 Hint: If you distribute a bunch of scripts you can pack them together with the
6396 |vimball| utility. Also read the user manual |distribute-script|.
6398 ==============================================================================
6399 6. Curly braces names *curly-braces-names*
6401 Wherever you can use a variable, you can use a "curly braces name" variable.
6402 This is a regular variable name with one or more expressions wrapped in braces
6403 {} like this: >
6404 my_{adjective}_variable
6406 When Vim encounters this, it evaluates the expression inside the braces, puts
6407 that in place of the expression, and re-interprets the whole as a variable
6408 name. So in the above example, if the variable "adjective" was set to
6409 "noisy", then the reference would be to "my_noisy_variable", whereas if
6410 "adjective" was set to "quiet", then it would be to "my_quiet_variable".
6412 One application for this is to create a set of variables governed by an option
6413 value. For example, the statement >
6414 echo my_{&background}_message
6416 would output the contents of "my_dark_message" or "my_light_message" depending
6417 on the current value of 'background'.
6419 You can use multiple brace pairs: >
6420 echo my_{adverb}_{adjective}_message
6421 ..or even nest them: >
6422 echo my_{ad{end_of_word}}_message
6423 where "end_of_word" is either "verb" or "jective".
6425 However, the expression inside the braces must evaluate to a valid single
6426 variable name, e.g. this is invalid: >
6427 :let foo='a + b'
6428 :echo c{foo}d
6429 .. since the result of expansion is "ca + bd", which is not a variable name.
6431 *curly-braces-function-names*
6432 You can call and define functions by an evaluated name in a similar way.
6433 Example: >
6434 :let func_end='whizz'
6435 :call my_func_{func_end}(parameter)
6437 This would call the function "my_func_whizz(parameter)".
6439 ==============================================================================
6440 7. Commands *expression-commands*
6442 :let {var-name} = {expr1} *:let* *E18*
6443 Set internal variable {var-name} to the result of the
6444 expression {expr1}. The variable will get the type
6445 from the {expr}. If {var-name} didn't exist yet, it
6446 is created.
6448 :let {var-name}[{idx}] = {expr1} *E689*
6449 Set a list item to the result of the expression
6450 {expr1}. {var-name} must refer to a list and {idx}
6451 must be a valid index in that list. For nested list
6452 the index can be repeated.
6453 This cannot be used to add an item to a |List|.
6454 This cannot be used to set a byte in a String. You
6455 can do that like this: >
6456 :let var = var[0:2] . 'X' . var[4:]
6457 <
6458 *E711* *E719*
6459 :let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710*
6460 Set a sequence of items in a |List| to the result of
6461 the expression {expr1}, which must be a list with the
6462 correct number of items.
6463 {idx1} can be omitted, zero is used instead.
6464 {idx2} can be omitted, meaning the end of the list.
6465 When the selected range of items is partly past the
6466 end of the list, items will be added.
6468 *:let+=* *:let-=* *:let.=* *E734*
6469 :let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
6470 :let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
6471 :let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
6472 These fail if {var} was not set yet and when the type
6473 of {var} and {expr1} don't fit the operator.
6476 :let ${env-name} = {expr1} *:let-environment* *:let-$*
6477 Set environment variable {env-name} to the result of
6478 the expression {expr1}. The type is always String.
6479 :let ${env-name} .= {expr1}
6480 Append {expr1} to the environment variable {env-name}.
6481 If the environment variable didn't exist yet this
6482 works like "=".
6484 :let @{reg-name} = {expr1} *:let-register* *:let-@*
6485 Write the result of the expression {expr1} in register
6486 {reg-name}. {reg-name} must be a single letter, and
6487 must be the name of a writable register (see
6488 |registers|). "@@" can be used for the unnamed
6489 register, "@/" for the search pattern.
6490 If the result of {expr1} ends in a <CR> or <NL>, the
6491 register will be linewise, otherwise it will be set to
6492 characterwise.
6493 This can be used to clear the last search pattern: >
6494 :let @/ = ""
6495 < This is different from searching for an empty string,
6496 that would match everywhere.
6498 :let @{reg-name} .= {expr1}
6499 Append {expr1} to register {reg-name}. If the
6500 register was empty it's like setting it to {expr1}.
6502 :let &{option-name} = {expr1} *:let-option* *:let-&*
6503 Set option {option-name} to the result of the
6504 expression {expr1}. A String or Number value is
6505 always converted to the type of the option.
6506 For an option local to a window or buffer the effect
6507 is just like using the |:set| command: both the local
6508 value and the global value are changed.
6509 Example: >
6510 :let &path = &path . ',/usr/local/include'
6512 :let &{option-name} .= {expr1}
6513 For a string option: Append {expr1} to the value.
6514 Does not insert a comma like |:set+=|.
6516 :let &{option-name} += {expr1}
6517 :let &{option-name} -= {expr1}
6518 For a number or boolean option: Add or subtract
6519 {expr1}.
6521 :let &l:{option-name} = {expr1}
6522 :let &l:{option-name} .= {expr1}
6523 :let &l:{option-name} += {expr1}
6524 :let &l:{option-name} -= {expr1}
6525 Like above, but only set the local value of an option
6526 (if there is one). Works like |:setlocal|.
6528 :let &g:{option-name} = {expr1}
6529 :let &g:{option-name} .= {expr1}
6530 :let &g:{option-name} += {expr1}
6531 :let &g:{option-name} -= {expr1}
6532 Like above, but only set the global value of an option
6533 (if there is one). Works like |:setglobal|.
6535 :let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
6536 {expr1} must evaluate to a |List|. The first item in
6537 the list is assigned to {name1}, the second item to
6538 {name2}, etc.
6539 The number of names must match the number of items in
6540 the |List|.
6541 Each name can be one of the items of the ":let"
6542 command as mentioned above.
6543 Example: >
6544 :let [s, item] = GetItem(s)
6545 < Detail: {expr1} is evaluated first, then the
6546 assignments are done in sequence. This matters if
6547 {name2} depends on {name1}. Example: >
6548 :let x = [0, 1]
6549 :let i = 0
6550 :let [i, x[i]] = [1, 2]
6551 :echo x
6552 < The result is [0, 2].
6554 :let [{name1}, {name2}, ...] .= {expr1}
6555 :let [{name1}, {name2}, ...] += {expr1}
6556 :let [{name1}, {name2}, ...] -= {expr1}
6557 Like above, but append/add/subtract the value for each
6558 |List| item.
6560 :let [{name}, ..., ; {lastname}] = {expr1}
6561 Like |:let-unpack| above, but the |List| may have more
6562 items than there are names. A list of the remaining
6563 items is assigned to {lastname}. If there are no
6564 remaining items {lastname} is set to an empty list.
6565 Example: >
6566 :let [a, b; rest] = ["aval", "bval", 3, 4]
6567 <
6568 :let [{name}, ..., ; {lastname}] .= {expr1}
6569 :let [{name}, ..., ; {lastname}] += {expr1}
6570 :let [{name}, ..., ; {lastname}] -= {expr1}
6571 Like above, but append/add/subtract the value for each
6572 |List| item.
6573 *E106*
6574 :let {var-name} .. List the value of variable {var-name}. Multiple
6575 variable names may be given. Special names recognized
6576 here: *E738*
6577 g: global variables
6578 b: local buffer variables
6579 w: local window variables
6580 t: local tab page variables
6581 s: script-local variables
6582 l: local function variables
6583 v: Vim variables.
6585 :let List the values of all variables. The type of the
6586 variable is indicated before the value:
6587 <nothing> String
6588 # Number
6589 * Funcref
6592 :unl[et][!] {name} ... *:unlet* *:unl* *E108* *E795*
6593 Remove the internal variable {name}. Several variable
6594 names can be given, they are all removed. The name
6595 may also be a |List| or |Dictionary| item.
6596 With [!] no error message is given for non-existing
6597 variables.
6598 One or more items from a |List| can be removed: >
6599 :unlet list[3] " remove fourth item
6600 :unlet list[3:] " remove fourth item to last
6601 < One item from a |Dictionary| can be removed at a time: >
6602 :unlet dict['two']
6603 :unlet dict.two
6604 < This is especially useful to clean up used global
6605 variables and script-local variables (these are not
6606 deleted when the script ends). Function-local
6607 variables are automatically deleted when the function
6608 ends.
6610 :lockv[ar][!] [depth] {name} ... *:lockvar* *:lockv*
6611 Lock the internal variable {name}. Locking means that
6612 it can no longer be changed (until it is unlocked).
6613 A locked variable can be deleted: >
6614 :lockvar v
6615 :let v = 'asdf' " fails!
6616 :unlet v
6617 < *E741*
6618 If you try to change a locked variable you get an
6619 error message: "E741: Value of {name} is locked"
6621 [depth] is relevant when locking a |List| or
6622 |Dictionary|. It specifies how deep the locking goes:
6623 1 Lock the |List| or |Dictionary| itself,
6624 cannot add or remove items, but can
6625 still change their values.
6626 2 Also lock the values, cannot change
6627 the items. If an item is a |List| or
6628 |Dictionary|, cannot add or remove
6629 items, but can still change the
6630 values.
6631 3 Like 2 but for the |List| /
6632 |Dictionary| in the |List| /
6633 |Dictionary|, one level deeper.
6634 The default [depth] is 2, thus when {name} is a |List|
6635 or |Dictionary| the values cannot be changed.
6636 *E743*
6637 For unlimited depth use [!] and omit [depth].
6638 However, there is a maximum depth of 100 to catch
6639 loops.
6641 Note that when two variables refer to the same |List|
6642 and you lock one of them, the |List| will also be
6643 locked when used through the other variable.
6644 Example: >
6645 :let l = [0, 1, 2, 3]
6646 :let cl = l
6647 :lockvar l
6648 :let cl[1] = 99 " won't work!
6649 < You may want to make a copy of a list to avoid this.
6650 See |deepcopy()|.
6653 :unlo[ckvar][!] [depth] {name} ... *:unlockvar* *:unlo*
6654 Unlock the internal variable {name}. Does the
6655 opposite of |:lockvar|.
6658 :if {expr1} *:if* *:endif* *:en* *E171* *E579* *E580*
6659 :en[dif] Execute the commands until the next matching ":else"
6660 or ":endif" if {expr1} evaluates to non-zero.
6662 From Vim version 4.5 until 5.0, every Ex command in
6663 between the ":if" and ":endif" is ignored. These two
6664 commands were just to allow for future expansions in a
6665 backwards compatible way. Nesting was allowed. Note
6666 that any ":else" or ":elseif" was ignored, the "else"
6667 part was not executed either.
6669 You can use this to remain compatible with older
6670 versions: >
6671 :if version >= 500
6672 : version-5-specific-commands
6673 :endif
6674 < The commands still need to be parsed to find the
6675 "endif". Sometimes an older Vim has a problem with a
6676 new command. For example, ":silent" is recognized as
6677 a ":substitute" command. In that case ":execute" can
6678 avoid problems: >
6679 :if version >= 600
6680 : execute "silent 1,$delete"
6681 :endif
6682 <
6683 NOTE: The ":append" and ":insert" commands don't work
6684 properly in between ":if" and ":endif".
6686 *:else* *:el* *E581* *E583*
6687 :el[se] Execute the commands until the next matching ":else"
6688 or ":endif" if they previously were not being
6689 executed.
6691 *:elseif* *:elsei* *E582* *E584*
6692 :elsei[f] {expr1} Short for ":else" ":if", with the addition that there
6693 is no extra ":endif".
6695 :wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw*
6696 *E170* *E585* *E588* *E733*
6697 :endw[hile] Repeat the commands between ":while" and ":endwhile",
6698 as long as {expr1} evaluates to non-zero.
6699 When an error is detected from a command inside the
6700 loop, execution continues after the "endwhile".
6701 Example: >
6702 :let lnum = 1
6703 :while lnum <= line("$")
6704 :call FixLine(lnum)
6705 :let lnum = lnum + 1
6706 :endwhile
6707 <
6708 NOTE: The ":append" and ":insert" commands don't work
6709 properly inside a ":while" and ":for" loop.
6711 :for {var} in {list} *:for* *E690* *E732*
6712 :endfo[r] *:endfo* *:endfor*
6713 Repeat the commands between ":for" and ":endfor" for
6714 each item in {list}. Variable {var} is set to the
6715 value of each item.
6716 When an error is detected for a command inside the
6717 loop, execution continues after the "endfor".
6718 Changing {list} inside the loop affects what items are
6719 used. Make a copy if this is unwanted: >
6720 :for item in copy(mylist)
6721 < When not making a copy, Vim stores a reference to the
6722 next item in the list, before executing the commands
6723 with the current item. Thus the current item can be
6724 removed without effect. Removing any later item means
6725 it will not be found. Thus the following example
6726 works (an inefficient way to make a list empty): >
6727 for item in mylist
6728 call remove(mylist, 0)
6729 endfor
6730 < Note that reordering the list (e.g., with sort() or
6731 reverse()) may have unexpected effects.
6732 Note that the type of each list item should be
6733 identical to avoid errors for the type of {var}
6734 changing. Unlet the variable at the end of the loop
6735 to allow multiple item types: >
6736 for item in ["foo", ["bar"]]
6737 echo item
6738 unlet item " E706 without this
6739 endfor
6741 :for [{var1}, {var2}, ...] in {listlist}
6742 :endfo[r]
6743 Like ":for" above, but each item in {listlist} must be
6744 a list, of which each item is assigned to {var1},
6745 {var2}, etc. Example: >
6746 :for [lnum, col] in [[1, 3], [2, 5], [3, 8]]
6747 :echo getline(lnum)[col]
6748 :endfor
6749 <
6750 *:continue* *:con* *E586*
6751 :con[tinue] When used inside a ":while" or ":for" loop, jumps back
6752 to the start of the loop.
6753 If it is used after a |:try| inside the loop but
6754 before the matching |:finally| (if present), the
6755 commands following the ":finally" up to the matching
6756 |:endtry| are executed first. This process applies to
6757 all nested ":try"s inside the loop. The outermost
6758 ":endtry" then jumps back to the start of the loop.
6760 *:break* *:brea* *E587*
6761 :brea[k] When used inside a ":while" or ":for" loop, skips to
6762 the command after the matching ":endwhile" or
6763 ":endfor".
6764 If it is used after a |:try| inside the loop but
6765 before the matching |:finally| (if present), the
6766 commands following the ":finally" up to the matching
6767 |:endtry| are executed first. This process applies to
6768 all nested ":try"s inside the loop. The outermost
6769 ":endtry" then jumps to the command after the loop.
6771 :try *:try* *:endt* *:endtry* *E600* *E601* *E602*
6772 :endt[ry] Change the error handling for the commands between
6773 ":try" and ":endtry" including everything being
6774 executed across ":source" commands, function calls,
6775 or autocommand invocations.
6777 When an error or interrupt is detected and there is
6778 a |:finally| command following, execution continues
6779 after the ":finally". Otherwise, or when the
6780 ":endtry" is reached thereafter, the next
6781 (dynamically) surrounding ":try" is checked for
6782 a corresponding ":finally" etc. Then the script
6783 processing is terminated. (Whether a function
6784 definition has an "abort" argument does not matter.)
6785 Example: >
6786 :try | edit too much | finally | echo "cleanup" | endtry
6787 :echo "impossible" " not reached, script terminated above
6788 <
6789 Moreover, an error or interrupt (dynamically) inside
6790 ":try" and ":endtry" is converted to an exception. It
6791 can be caught as if it were thrown by a |:throw|
6792 command (see |:catch|). In this case, the script
6793 processing is not terminated.
6795 The value "Vim:Interrupt" is used for an interrupt
6796 exception. An error in a Vim command is converted
6797 to a value of the form "Vim({command}):{errmsg}",
6798 other errors are converted to a value of the form
6799 "Vim:{errmsg}". {command} is the full command name,
6800 and {errmsg} is the message that is displayed if the
6801 error exception is not caught, always beginning with
6802 the error number.
6803 Examples: >
6804 :try | sleep 100 | catch /^Vim:Interrupt$/ | endtry
6805 :try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry
6806 <
6807 *:cat* *:catch* *E603* *E604* *E605*
6808 :cat[ch] /{pattern}/ The following commands until the next |:catch|,
6809 |:finally|, or |:endtry| that belongs to the same
6810 |:try| as the ":catch" are executed when an exception
6811 matching {pattern} is being thrown and has not yet
6812 been caught by a previous ":catch". Otherwise, these
6813 commands are skipped.
6814 When {pattern} is omitted all errors are caught.
6815 Examples: >
6816 :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C)
6817 :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors
6818 :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts
6819 :catch /^Vim(write):/ " catch all errors in :write
6820 :catch /^Vim\%((\a\+)\)\=:E123/ " catch error E123
6821 :catch /my-exception/ " catch user exception
6822 :catch /.*/ " catch everything
6823 :catch " same as /.*/
6824 <
6825 Another character can be used instead of / around the
6826 {pattern}, so long as it does not have a special
6827 meaning (e.g., '|' or '"') and doesn't occur inside
6828 {pattern}.
6829 NOTE: It is not reliable to ":catch" the TEXT of
6830 an error message because it may vary in different
6831 locales.
6833 *:fina* *:finally* *E606* *E607*
6834 :fina[lly] The following commands until the matching |:endtry|
6835 are executed whenever the part between the matching
6836 |:try| and the ":finally" is left: either by falling
6837 through to the ":finally" or by a |:continue|,
6838 |:break|, |:finish|, or |:return|, or by an error or
6839 interrupt or exception (see |:throw|).
6841 *:th* *:throw* *E608*
6842 :th[row] {expr1} The {expr1} is evaluated and thrown as an exception.
6843 If the ":throw" is used after a |:try| but before the
6844 first corresponding |:catch|, commands are skipped
6845 until the first ":catch" matching {expr1} is reached.
6846 If there is no such ":catch" or if the ":throw" is
6847 used after a ":catch" but before the |:finally|, the
6848 commands following the ":finally" (if present) up to
6849 the matching |:endtry| are executed. If the ":throw"
6850 is after the ":finally", commands up to the ":endtry"
6851 are skipped. At the ":endtry", this process applies
6852 again for the next dynamically surrounding ":try"
6853 (which may be found in a calling function or sourcing
6854 script), until a matching ":catch" has been found.
6855 If the exception is not caught, the command processing
6856 is terminated.
6857 Example: >
6858 :try | throw "oops" | catch /^oo/ | echo "caught" | endtry
6859 <
6861 *:ec* *:echo*
6862 :ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The
6863 first {expr1} starts on a new line.
6864 Also see |:comment|.
6865 Use "\n" to start a new line. Use "\r" to move the
6866 cursor to the first column.
6867 Uses the highlighting set by the |:echohl| command.
6868 Cannot be followed by a comment.
6869 Example: >
6870 :echo "the value of 'shell' is" &shell
6871 < *:echo-redraw*
6872 A later redraw may make the message disappear again.
6873 And since Vim mostly postpones redrawing until it's
6874 finished with a sequence of commands this happens
6875 quite often. To avoid that a command from before the
6876 ":echo" causes a redraw afterwards (redraws are often
6877 postponed until you type something), force a redraw
6878 with the |:redraw| command. Example: >
6879 :new | redraw | echo "there is a new window"
6880 <
6881 *:echon*
6882 :echon {expr1} .. Echoes each {expr1}, without anything added. Also see
6883 |:comment|.
6884 Uses the highlighting set by the |:echohl| command.
6885 Cannot be followed by a comment.
6886 Example: >
6887 :echon "the value of 'shell' is " &shell
6888 <
6889 Note the difference between using ":echo", which is a
6890 Vim command, and ":!echo", which is an external shell
6891 command: >
6892 :!echo % --> filename
6893 < The arguments of ":!" are expanded, see |:_%|. >
6894 :!echo "%" --> filename or "filename"
6895 < Like the previous example. Whether you see the double
6896 quotes or not depends on your 'shell'. >
6897 :echo % --> nothing
6898 < The '%' is an illegal character in an expression. >
6899 :echo "%" --> %
6900 < This just echoes the '%' character. >
6901 :echo expand("%") --> filename
6902 < This calls the expand() function to expand the '%'.
6904 *:echoh* *:echohl*
6905 :echoh[l] {name} Use the highlight group {name} for the following
6906 |:echo|, |:echon| and |:echomsg| commands. Also used
6907 for the |input()| prompt. Example: >
6908 :echohl WarningMsg | echo "Don't panic!" | echohl None
6909 < Don't forget to set the group back to "None",
6910 otherwise all following echo's will be highlighted.
6912 *:echom* *:echomsg*
6913 :echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the
6914 message in the |message-history|.
6915 Spaces are placed between the arguments as with the
6916 |:echo| command. But unprintable characters are
6917 displayed, not interpreted.
6918 The parsing works slightly different from |:echo|,
6919 more like |:execute|. All the expressions are first
6920 evaluated and concatenated before echoing anything.
6921 The expressions must evaluate to a Number or String, a
6922 Dictionary or List causes an error.
6923 Uses the highlighting set by the |:echohl| command.
6924 Example: >
6925 :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."
6926 < See |:echo-redraw| to avoid the message disappearing
6927 when the screen is redrawn.
6928 *:echoe* *:echoerr*
6929 :echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the
6930 message in the |message-history|. When used in a
6931 script or function the line number will be added.
6932 Spaces are placed between the arguments as with the
6933 :echo command. When used inside a try conditional,
6934 the message is raised as an error exception instead
6935 (see |try-echoerr|).
6936 Example: >
6937 :echoerr "This script just failed!"
6938 < If you just want a highlighted message use |:echohl|.
6939 And to get a beep: >
6940 :exe "normal \<Esc>"
6941 <
6942 *:exe* *:execute*
6943 :exe[cute] {expr1} .. Executes the string that results from the evaluation
6944 of {expr1} as an Ex command. Multiple arguments are
6945 concatenated, with a space in between. {expr1} is
6946 used as the processed command, command line editing
6947 keys are not recognized.
6948 Cannot be followed by a comment.
6949 Examples: >
6950 :execute "buffer " nextbuf
6951 :execute "normal " count . "w"
6952 <
6953 ":execute" can be used to append a command to commands
6954 that don't accept a '|'. Example: >
6955 :execute '!ls' | echo "theend"
6957 < ":execute" is also a nice way to avoid having to type
6958 control characters in a Vim script for a ":normal"
6959 command: >
6960 :execute "normal ixxx\<Esc>"
6961 < This has an <Esc> character, see |expr-string|.
6963 Be careful to correctly escape special characters in
6964 file names. The |fnameescape()| function can be used
6965 for Vim commands, |shellescape()| for |:!| commands.
6966 Examples: >
6967 :execute "e " . fnameescape(filename)
6968 :execute "!ls " . shellescape(expand('%:h'), 1)
6969 <
6970 Note: The executed string may be any command-line, but
6971 you cannot start or end a "while", "for" or "if"
6972 command. Thus this is illegal: >
6973 :execute 'while i > 5'
6974 :execute 'echo "test" | break'
6975 <
6976 It is allowed to have a "while" or "if" command
6977 completely in the executed string: >
6978 :execute 'while i < 5 | echo i | let i = i + 1 | endwhile'
6979 <
6981 *:exe-comment*
6982 ":execute", ":echo" and ":echon" cannot be followed by
6983 a comment directly, because they see the '"' as the
6984 start of a string. But, you can use '|' followed by a
6985 comment. Example: >
6986 :echo "foo" | "this is a comment
6988 ==============================================================================
6989 8. Exception handling *exception-handling*
6991 The Vim script language comprises an exception handling feature. This section
6992 explains how it can be used in a Vim script.
6994 Exceptions may be raised by Vim on an error or on interrupt, see
6995 |catch-errors| and |catch-interrupt|. You can also explicitly throw an
6996 exception by using the ":throw" command, see |throw-catch|.
6999 TRY CONDITIONALS *try-conditionals*
7001 Exceptions can be caught or can cause cleanup code to be executed. You can
7002 use a try conditional to specify catch clauses (that catch exceptions) and/or
7003 a finally clause (to be executed for cleanup).
7004 A try conditional begins with a |:try| command and ends at the matching
7005 |:endtry| command. In between, you can use a |:catch| command to start
7006 a catch clause, or a |:finally| command to start a finally clause. There may
7007 be none or multiple catch clauses, but there is at most one finally clause,
7008 which must not be followed by any catch clauses. The lines before the catch
7009 clauses and the finally clause is called a try block. >
7011 :try
7012 : ...
7013 : ... TRY BLOCK
7014 : ...
7015 :catch /{pattern}/
7016 : ...
7017 : ... CATCH CLAUSE
7018 : ...
7019 :catch /{pattern}/
7020 : ...
7021 : ... CATCH CLAUSE
7022 : ...
7023 :finally
7024 : ...
7025 : ... FINALLY CLAUSE
7026 : ...
7027 :endtry
7029 The try conditional allows to watch code for exceptions and to take the
7030 appropriate actions. Exceptions from the try block may be caught. Exceptions
7031 from the try block and also the catch clauses may cause cleanup actions.
7032 When no exception is thrown during execution of the try block, the control
7033 is transferred to the finally clause, if present. After its execution, the
7034 script continues with the line following the ":endtry".
7035 When an exception occurs during execution of the try block, the remaining
7036 lines in the try block are skipped. The exception is matched against the
7037 patterns specified as arguments to the ":catch" commands. The catch clause
7038 after the first matching ":catch" is taken, other catch clauses are not
7039 executed. The catch clause ends when the next ":catch", ":finally", or
7040 ":endtry" command is reached - whatever is first. Then, the finally clause
7041 (if present) is executed. When the ":endtry" is reached, the script execution
7042 continues in the following line as usual.
7043 When an exception that does not match any of the patterns specified by the
7044 ":catch" commands is thrown in the try block, the exception is not caught by
7045 that try conditional and none of the catch clauses is executed. Only the
7046 finally clause, if present, is taken. The exception pends during execution of
7047 the finally clause. It is resumed at the ":endtry", so that commands after
7048 the ":endtry" are not executed and the exception might be caught elsewhere,
7049 see |try-nesting|.
7050 When during execution of a catch clause another exception is thrown, the
7051 remaining lines in that catch clause are not executed. The new exception is
7052 not matched against the patterns in any of the ":catch" commands of the same
7053 try conditional and none of its catch clauses is taken. If there is, however,
7054 a finally clause, it is executed, and the exception pends during its
7055 execution. The commands following the ":endtry" are not executed. The new
7056 exception might, however, be caught elsewhere, see |try-nesting|.
7057 When during execution of the finally clause (if present) an exception is
7058 thrown, the remaining lines in the finally clause are skipped. If the finally
7059 clause has been taken because of an exception from the try block or one of the
7060 catch clauses, the original (pending) exception is discarded. The commands
7061 following the ":endtry" are not executed, and the exception from the finally
7062 clause is propagated and can be caught elsewhere, see |try-nesting|.
7064 The finally clause is also executed, when a ":break" or ":continue" for
7065 a ":while" loop enclosing the complete try conditional is executed from the
7066 try block or a catch clause. Or when a ":return" or ":finish" is executed
7067 from the try block or a catch clause of a try conditional in a function or
7068 sourced script, respectively. The ":break", ":continue", ":return", or
7069 ":finish" pends during execution of the finally clause and is resumed when the
7070 ":endtry" is reached. It is, however, discarded when an exception is thrown
7071 from the finally clause.
7072 When a ":break" or ":continue" for a ":while" loop enclosing the complete
7073 try conditional or when a ":return" or ":finish" is encountered in the finally
7074 clause, the rest of the finally clause is skipped, and the ":break",
7075 ":continue", ":return" or ":finish" is executed as usual. If the finally
7076 clause has been taken because of an exception or an earlier ":break",
7077 ":continue", ":return", or ":finish" from the try block or a catch clause,
7078 this pending exception or command is discarded.
7080 For examples see |throw-catch| and |try-finally|.
7083 NESTING OF TRY CONDITIONALS *try-nesting*
7085 Try conditionals can be nested arbitrarily. That is, a complete try
7086 conditional can be put into the try block, a catch clause, or the finally
7087 clause of another try conditional. If the inner try conditional does not
7088 catch an exception thrown in its try block or throws a new exception from one
7089 of its catch clauses or its finally clause, the outer try conditional is
7090 checked according to the rules above. If the inner try conditional is in the
7091 try block of the outer try conditional, its catch clauses are checked, but
7092 otherwise only the finally clause is executed. It does not matter for
7093 nesting, whether the inner try conditional is directly contained in the outer
7094 one, or whether the outer one sources a script or calls a function containing
7095 the inner try conditional.
7097 When none of the active try conditionals catches an exception, just their
7098 finally clauses are executed. Thereafter, the script processing terminates.
7099 An error message is displayed in case of an uncaught exception explicitly
7100 thrown by a ":throw" command. For uncaught error and interrupt exceptions
7101 implicitly raised by Vim, the error message(s) or interrupt message are shown
7102 as usual.
7104 For examples see |throw-catch|.
7107 EXAMINING EXCEPTION HANDLING CODE *except-examine*
7109 Exception handling code can get tricky. If you are in doubt what happens, set
7110 'verbose' to 13 or use the ":13verbose" command modifier when sourcing your
7111 script file. Then you see when an exception is thrown, discarded, caught, or
7112 finished. When using a verbosity level of at least 14, things pending in
7113 a finally clause are also shown. This information is also given in debug mode
7114 (see |debug-scripts|).
7117 THROWING AND CATCHING EXCEPTIONS *throw-catch*
7119 You can throw any number or string as an exception. Use the |:throw| command
7120 and pass the value to be thrown as argument: >
7121 :throw 4711
7122 :throw "string"
7123 < *throw-expression*
7124 You can also specify an expression argument. The expression is then evaluated
7125 first, and the result is thrown: >
7126 :throw 4705 + strlen("string")
7127 :throw strpart("strings", 0, 6)
7129 An exception might be thrown during evaluation of the argument of the ":throw"
7130 command. Unless it is caught there, the expression evaluation is abandoned.
7131 The ":throw" command then does not throw a new exception.
7132 Example: >
7134 :function! Foo(arg)
7135 : try
7136 : throw a:arg
7137 : catch /foo/
7138 : endtry
7139 : return 1
7140 :endfunction
7141 :
7142 :function! Bar()
7143 : echo "in Bar"
7144 : return 4710
7145 :endfunction
7146 :
7147 :throw Foo("arrgh") + Bar()
7149 This throws "arrgh", and "in Bar" is not displayed since Bar() is not
7150 executed. >
7151 :throw Foo("foo") + Bar()
7152 however displays "in Bar" and throws 4711.
7154 Any other command that takes an expression as argument might also be
7155 abandoned by an (uncaught) exception during the expression evaluation. The
7156 exception is then propagated to the caller of the command.
7157 Example: >
7159 :if Foo("arrgh")
7160 : echo "then"
7161 :else
7162 : echo "else"
7163 :endif
7165 Here neither of "then" or "else" is displayed.
7167 *catch-order*
7168 Exceptions can be caught by a try conditional with one or more |:catch|
7169 commands, see |try-conditionals|. The values to be caught by each ":catch"
7170 command can be specified as a pattern argument. The subsequent catch clause
7171 gets executed when a matching exception is caught.
7172 Example: >
7174 :function! Foo(value)
7175 : try
7176 : throw a:value
7177 : catch /^\d\+$/
7178 : echo "Number thrown"
7179 : catch /.*/
7180 : echo "String thrown"
7181 : endtry
7182 :endfunction
7183 :
7184 :call Foo(0x1267)
7185 :call Foo('string')
7187 The first call to Foo() displays "Number thrown", the second "String thrown".
7188 An exception is matched against the ":catch" commands in the order they are
7189 specified. Only the first match counts. So you should place the more
7190 specific ":catch" first. The following order does not make sense: >
7192 : catch /.*/
7193 : echo "String thrown"
7194 : catch /^\d\+$/
7195 : echo "Number thrown"
7197 The first ":catch" here matches always, so that the second catch clause is
7198 never taken.
7200 *throw-variables*
7201 If you catch an exception by a general pattern, you may access the exact value
7202 in the variable |v:exception|: >
7204 : catch /^\d\+$/
7205 : echo "Number thrown. Value is" v:exception
7207 You may also be interested where an exception was thrown. This is stored in
7208 |v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the
7209 exception most recently caught as long it is not finished.
7210 Example: >
7212 :function! Caught()
7213 : if v:exception != ""
7214 : echo 'Caught "' . v:exception . '" in ' . v:throwpoint
7215 : else
7216 : echo 'Nothing caught'
7217 : endif
7218 :endfunction
7219 :
7220 :function! Foo()
7221 : try
7222 : try
7223 : try
7224 : throw 4711
7225 : finally
7226 : call Caught()
7227 : endtry
7228 : catch /.*/
7229 : call Caught()
7230 : throw "oops"
7231 : endtry
7232 : catch /.*/
7233 : call Caught()
7234 : finally
7235 : call Caught()
7236 : endtry
7237 :endfunction
7238 :
7239 :call Foo()
7241 This displays >
7243 Nothing caught
7244 Caught "4711" in function Foo, line 4
7245 Caught "oops" in function Foo, line 10
7246 Nothing caught
7248 A practical example: The following command ":LineNumber" displays the line
7249 number in the script or function where it has been used: >
7251 :function! LineNumber()
7252 : return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")
7253 :endfunction
7254 :command! LineNumber try | throw "" | catch | echo LineNumber() | endtry
7255 <
7256 *try-nested*
7257 An exception that is not caught by a try conditional can be caught by
7258 a surrounding try conditional: >
7260 :try
7261 : try
7262 : throw "foo"
7263 : catch /foobar/
7264 : echo "foobar"
7265 : finally
7266 : echo "inner finally"
7267 : endtry
7268 :catch /foo/
7269 : echo "foo"
7270 :endtry
7272 The inner try conditional does not catch the exception, just its finally
7273 clause is executed. The exception is then caught by the outer try
7274 conditional. The example displays "inner finally" and then "foo".
7276 *throw-from-catch*
7277 You can catch an exception and throw a new one to be caught elsewhere from the
7278 catch clause: >
7280 :function! Foo()
7281 : throw "foo"
7282 :endfunction
7283 :
7284 :function! Bar()
7285 : try
7286 : call Foo()
7287 : catch /foo/
7288 : echo "Caught foo, throw bar"
7289 : throw "bar"
7290 : endtry
7291 :endfunction
7292 :
7293 :try
7294 : call Bar()
7295 :catch /.*/
7296 : echo "Caught" v:exception
7297 :endtry
7299 This displays "Caught foo, throw bar" and then "Caught bar".
7301 *rethrow*
7302 There is no real rethrow in the Vim script language, but you may throw
7303 "v:exception" instead: >
7305 :function! Bar()
7306 : try
7307 : call Foo()
7308 : catch /.*/
7309 : echo "Rethrow" v:exception
7310 : throw v:exception
7311 : endtry
7312 :endfunction
7313 < *try-echoerr*
7314 Note that this method cannot be used to "rethrow" Vim error or interrupt
7315 exceptions, because it is not possible to fake Vim internal exceptions.
7316 Trying so causes an error exception. You should throw your own exception
7317 denoting the situation. If you want to cause a Vim error exception containing
7318 the original error exception value, you can use the |:echoerr| command: >
7320 :try
7321 : try
7322 : asdf
7323 : catch /.*/
7324 : echoerr v:exception
7325 : endtry
7326 :catch /.*/
7327 : echo v:exception
7328 :endtry
7330 This code displays
7332 Vim(echoerr):Vim:E492: Not an editor command: asdf ~
7335 CLEANUP CODE *try-finally*
7337 Scripts often change global settings and restore them at their end. If the
7338 user however interrupts the script by pressing CTRL-C, the settings remain in
7339 an inconsistent state. The same may happen to you in the development phase of
7340 a script when an error occurs or you explicitly throw an exception without
7341 catching it. You can solve these problems by using a try conditional with
7342 a finally clause for restoring the settings. Its execution is guaranteed on
7343 normal control flow, on error, on an explicit ":throw", and on interrupt.
7344 (Note that errors and interrupts from inside the try conditional are converted
7345 to exceptions. When not caught, they terminate the script after the finally
7346 clause has been executed.)
7347 Example: >
7349 :try
7350 : let s:saved_ts = &ts
7351 : set ts=17
7352 :
7353 : " Do the hard work here.
7354 :
7355 :finally
7356 : let &ts = s:saved_ts
7357 : unlet s:saved_ts
7358 :endtry
7360 This method should be used locally whenever a function or part of a script
7361 changes global settings which need to be restored on failure or normal exit of
7362 that function or script part.
7364 *break-finally*
7365 Cleanup code works also when the try block or a catch clause is left by
7366 a ":continue", ":break", ":return", or ":finish".
7367 Example: >
7369 :let first = 1
7370 :while 1
7371 : try
7372 : if first
7373 : echo "first"
7374 : let first = 0
7375 : continue
7376 : else
7377 : throw "second"
7378 : endif
7379 : catch /.*/
7380 : echo v:exception
7381 : break
7382 : finally
7383 : echo "cleanup"
7384 : endtry
7385 : echo "still in while"
7386 :endwhile
7387 :echo "end"
7389 This displays "first", "cleanup", "second", "cleanup", and "end". >
7391 :function! Foo()
7392 : try
7393 : return 4711
7394 : finally
7395 : echo "cleanup\n"
7396 : endtry
7397 : echo "Foo still active"
7398 :endfunction
7399 :
7400 :echo Foo() "returned by Foo"
7402 This displays "cleanup" and "4711 returned by Foo". You don't need to add an
7403 extra ":return" in the finally clause. (Above all, this would override the
7404 return value.)
7406 *except-from-finally*
7407 Using either of ":continue", ":break", ":return", ":finish", or ":throw" in
7408 a finally clause is possible, but not recommended since it abandons the
7409 cleanup actions for the try conditional. But, of course, interrupt and error
7410 exceptions might get raised from a finally clause.
7411 Example where an error in the finally clause stops an interrupt from
7412 working correctly: >
7414 :try
7415 : try
7416 : echo "Press CTRL-C for interrupt"
7417 : while 1
7418 : endwhile
7419 : finally
7420 : unlet novar
7421 : endtry
7422 :catch /novar/
7423 :endtry
7424 :echo "Script still running"
7425 :sleep 1
7427 If you need to put commands that could fail into a finally clause, you should
7428 think about catching or ignoring the errors in these commands, see
7429 |catch-errors| and |ignore-errors|.
7432 CATCHING ERRORS *catch-errors*
7434 If you want to catch specific errors, you just have to put the code to be
7435 watched in a try block and add a catch clause for the error message. The
7436 presence of the try conditional causes all errors to be converted to an
7437 exception. No message is displayed and |v:errmsg| is not set then. To find
7438 the right pattern for the ":catch" command, you have to know how the format of
7439 the error exception is.
7440 Error exceptions have the following format: >
7442 Vim({cmdname}):{errmsg}
7443 or >
7444 Vim:{errmsg}
7446 {cmdname} is the name of the command that failed; the second form is used when
7447 the command name is not known. {errmsg} is the error message usually produced
7448 when the error occurs outside try conditionals. It always begins with
7449 a capital "E", followed by a two or three-digit error number, a colon, and
7450 a space.
7452 Examples:
7454 The command >
7455 :unlet novar
7456 normally produces the error message >
7457 E108: No such variable: "novar"
7458 which is converted inside try conditionals to an exception >
7459 Vim(unlet):E108: No such variable: "novar"
7461 The command >
7462 :dwim
7463 normally produces the error message >
7464 E492: Not an editor command: dwim
7465 which is converted inside try conditionals to an exception >
7466 Vim:E492: Not an editor command: dwim
7468 You can catch all ":unlet" errors by a >
7469 :catch /^Vim(unlet):/
7470 or all errors for misspelled command names by a >
7471 :catch /^Vim:E492:/
7473 Some error messages may be produced by different commands: >
7474 :function nofunc
7475 and >
7476 :delfunction nofunc
7477 both produce the error message >
7478 E128: Function name must start with a capital: nofunc
7479 which is converted inside try conditionals to an exception >
7480 Vim(function):E128: Function name must start with a capital: nofunc
7481 or >
7482 Vim(delfunction):E128: Function name must start with a capital: nofunc
7483 respectively. You can catch the error by its number independently on the
7484 command that caused it if you use the following pattern: >
7485 :catch /^Vim(\a\+):E128:/
7487 Some commands like >
7488 :let x = novar
7489 produce multiple error messages, here: >
7490 E121: Undefined variable: novar
7491 E15: Invalid expression: novar
7492 Only the first is used for the exception value, since it is the most specific
7493 one (see |except-several-errors|). So you can catch it by >
7494 :catch /^Vim(\a\+):E121:/
7496 You can catch all errors related to the name "nofunc" by >
7497 :catch /\<nofunc\>/
7499 You can catch all Vim errors in the ":write" and ":read" commands by >
7500 :catch /^Vim(\(write\|read\)):E\d\+:/
7502 You can catch all Vim errors by the pattern >
7503 :catch /^Vim\((\a\+)\)\=:E\d\+:/
7504 <
7505 *catch-text*
7506 NOTE: You should never catch the error message text itself: >
7507 :catch /No such variable/
7508 only works in the english locale, but not when the user has selected
7509 a different language by the |:language| command. It is however helpful to
7510 cite the message text in a comment: >
7511 :catch /^Vim(\a\+):E108:/ " No such variable
7514 IGNORING ERRORS *ignore-errors*
7516 You can ignore errors in a specific Vim command by catching them locally: >
7518 :try
7519 : write
7520 :catch
7521 :endtry
7523 But you are strongly recommended NOT to use this simple form, since it could
7524 catch more than you want. With the ":write" command, some autocommands could
7525 be executed and cause errors not related to writing, for instance: >
7527 :au BufWritePre * unlet novar
7529 There could even be such errors you are not responsible for as a script
7530 writer: a user of your script might have defined such autocommands. You would
7531 then hide the error from the user.
7532 It is much better to use >
7534 :try
7535 : write
7536 :catch /^Vim(write):/
7537 :endtry
7539 which only catches real write errors. So catch only what you'd like to ignore
7540 intentionally.
7542 For a single command that does not cause execution of autocommands, you could
7543 even suppress the conversion of errors to exceptions by the ":silent!"
7544 command: >
7545 :silent! nunmap k
7546 This works also when a try conditional is active.
7549 CATCHING INTERRUPTS *catch-interrupt*
7551 When there are active try conditionals, an interrupt (CTRL-C) is converted to
7552 the exception "Vim:Interrupt". You can catch it like every exception. The
7553 script is not terminated, then.
7554 Example: >
7556 :function! TASK1()
7557 : sleep 10
7558 :endfunction
7560 :function! TASK2()
7561 : sleep 20
7562 :endfunction
7564 :while 1
7565 : let command = input("Type a command: ")
7566 : try
7567 : if command == ""
7568 : continue
7569 : elseif command == "END"
7570 : break
7571 : elseif command == "TASK1"
7572 : call TASK1()
7573 : elseif command == "TASK2"
7574 : call TASK2()
7575 : else
7576 : echo "\nIllegal command:" command
7577 : continue
7578 : endif
7579 : catch /^Vim:Interrupt$/
7580 : echo "\nCommand interrupted"
7581 : " Caught the interrupt. Continue with next prompt.
7582 : endtry
7583 :endwhile
7585 You can interrupt a task here by pressing CTRL-C; the script then asks for
7586 a new command. If you press CTRL-C at the prompt, the script is terminated.
7588 For testing what happens when CTRL-C would be pressed on a specific line in
7589 your script, use the debug mode and execute the |>quit| or |>interrupt|
7590 command on that line. See |debug-scripts|.
7593 CATCHING ALL *catch-all*
7595 The commands >
7597 :catch /.*/
7598 :catch //
7599 :catch
7601 catch everything, error exceptions, interrupt exceptions and exceptions
7602 explicitly thrown by the |:throw| command. This is useful at the top level of
7603 a script in order to catch unexpected things.
7604 Example: >
7606 :try
7607 :
7608 : " do the hard work here
7609 :
7610 :catch /MyException/
7611 :
7612 : " handle known problem
7613 :
7614 :catch /^Vim:Interrupt$/
7615 : echo "Script interrupted"
7616 :catch /.*/
7617 : echo "Internal error (" . v:exception . ")"
7618 : echo " - occurred at " . v:throwpoint
7619 :endtry
7620 :" end of script
7622 Note: Catching all might catch more things than you want. Thus, you are
7623 strongly encouraged to catch only for problems that you can really handle by
7624 specifying a pattern argument to the ":catch".
7625 Example: Catching all could make it nearly impossible to interrupt a script
7626 by pressing CTRL-C: >
7628 :while 1
7629 : try
7630 : sleep 1
7631 : catch
7632 : endtry
7633 :endwhile
7636 EXCEPTIONS AND AUTOCOMMANDS *except-autocmd*
7638 Exceptions may be used during execution of autocommands. Example: >
7640 :autocmd User x try
7641 :autocmd User x throw "Oops!"
7642 :autocmd User x catch
7643 :autocmd User x echo v:exception
7644 :autocmd User x endtry
7645 :autocmd User x throw "Arrgh!"
7646 :autocmd User x echo "Should not be displayed"
7647 :
7648 :try
7649 : doautocmd User x
7650 :catch
7651 : echo v:exception
7652 :endtry
7654 This displays "Oops!" and "Arrgh!".
7656 *except-autocmd-Pre*
7657 For some commands, autocommands get executed before the main action of the
7658 command takes place. If an exception is thrown and not caught in the sequence
7659 of autocommands, the sequence and the command that caused its execution are
7660 abandoned and the exception is propagated to the caller of the command.
7661 Example: >
7663 :autocmd BufWritePre * throw "FAIL"
7664 :autocmd BufWritePre * echo "Should not be displayed"
7665 :
7666 :try
7667 : write
7668 :catch
7669 : echo "Caught:" v:exception "from" v:throwpoint
7670 :endtry
7672 Here, the ":write" command does not write the file currently being edited (as
7673 you can see by checking 'modified'), since the exception from the BufWritePre
7674 autocommand abandons the ":write". The exception is then caught and the
7675 script displays: >
7677 Caught: FAIL from BufWrite Auto commands for "*"
7678 <
7679 *except-autocmd-Post*
7680 For some commands, autocommands get executed after the main action of the
7681 command has taken place. If this main action fails and the command is inside
7682 an active try conditional, the autocommands are skipped and an error exception
7683 is thrown that can be caught by the caller of the command.
7684 Example: >
7686 :autocmd BufWritePost * echo "File successfully written!"
7687 :
7688 :try
7689 : write /i/m/p/o/s/s/i/b/l/e
7690 :catch
7691 : echo v:exception
7692 :endtry
7694 This just displays: >
7696 Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)
7698 If you really need to execute the autocommands even when the main action
7699 fails, trigger the event from the catch clause.
7700 Example: >
7702 :autocmd BufWritePre * set noreadonly
7703 :autocmd BufWritePost * set readonly
7704 :
7705 :try
7706 : write /i/m/p/o/s/s/i/b/l/e
7707 :catch
7708 : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e
7709 :endtry
7710 <
7711 You can also use ":silent!": >
7713 :let x = "ok"
7714 :let v:errmsg = ""
7715 :autocmd BufWritePost * if v:errmsg != ""
7716 :autocmd BufWritePost * let x = "after fail"
7717 :autocmd BufWritePost * endif
7718 :try
7719 : silent! write /i/m/p/o/s/s/i/b/l/e
7720 :catch
7721 :endtry
7722 :echo x
7724 This displays "after fail".
7726 If the main action of the command does not fail, exceptions from the
7727 autocommands will be catchable by the caller of the command: >
7729 :autocmd BufWritePost * throw ":-("
7730 :autocmd BufWritePost * echo "Should not be displayed"
7731 :
7732 :try
7733 : write
7734 :catch
7735 : echo v:exception
7736 :endtry
7737 <
7738 *except-autocmd-Cmd*
7739 For some commands, the normal action can be replaced by a sequence of
7740 autocommands. Exceptions from that sequence will be catchable by the caller
7741 of the command.
7742 Example: For the ":write" command, the caller cannot know whether the file
7743 had actually been written when the exception occurred. You need to tell it in
7744 some way. >
7746 :if !exists("cnt")
7747 : let cnt = 0
7748 :
7749 : autocmd BufWriteCmd * if &modified
7750 : autocmd BufWriteCmd * let cnt = cnt + 1
7751 : autocmd BufWriteCmd * if cnt % 3 == 2
7752 : autocmd BufWriteCmd * throw "BufWriteCmdError"
7753 : autocmd BufWriteCmd * endif
7754 : autocmd BufWriteCmd * write | set nomodified
7755 : autocmd BufWriteCmd * if cnt % 3 == 0
7756 : autocmd BufWriteCmd * throw "BufWriteCmdError"
7757 : autocmd BufWriteCmd * endif
7758 : autocmd BufWriteCmd * echo "File successfully written!"
7759 : autocmd BufWriteCmd * endif
7760 :endif
7761 :
7762 :try
7763 : write
7764 :catch /^BufWriteCmdError$/
7765 : if &modified
7766 : echo "Error on writing (file contents not changed)"
7767 : else
7768 : echo "Error after writing"
7769 : endif
7770 :catch /^Vim(write):/
7771 : echo "Error on writing"
7772 :endtry
7774 When this script is sourced several times after making changes, it displays
7775 first >
7776 File successfully written!
7777 then >
7778 Error on writing (file contents not changed)
7779 then >
7780 Error after writing
7781 etc.
7783 *except-autocmd-ill*
7784 You cannot spread a try conditional over autocommands for different events.
7785 The following code is ill-formed: >
7787 :autocmd BufWritePre * try
7788 :
7789 :autocmd BufWritePost * catch
7790 :autocmd BufWritePost * echo v:exception
7791 :autocmd BufWritePost * endtry
7792 :
7793 :write
7796 EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS *except-hier-param*
7798 Some programming languages allow to use hierarchies of exception classes or to
7799 pass additional information with the object of an exception class. You can do
7800 similar things in Vim.
7801 In order to throw an exception from a hierarchy, just throw the complete
7802 class name with the components separated by a colon, for instance throw the
7803 string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library.
7804 When you want to pass additional information with your exception class, add
7805 it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)"
7806 for an error when writing "myfile".
7807 With the appropriate patterns in the ":catch" command, you can catch for
7808 base classes or derived classes of your hierarchy. Additional information in
7809 parentheses can be cut out from |v:exception| with the ":substitute" command.
7810 Example: >
7812 :function! CheckRange(a, func)
7813 : if a:a < 0
7814 : throw "EXCEPT:MATHERR:RANGE(" . a:func . ")"
7815 : endif
7816 :endfunction
7817 :
7818 :function! Add(a, b)
7819 : call CheckRange(a:a, "Add")
7820 : call CheckRange(a:b, "Add")
7821 : let c = a:a + a:b
7822 : if c < 0
7823 : throw "EXCEPT:MATHERR:OVERFLOW"
7824 : endif
7825 : return c
7826 :endfunction
7827 :
7828 :function! Div(a, b)
7829 : call CheckRange(a:a, "Div")
7830 : call CheckRange(a:b, "Div")
7831 : if (a:b == 0)
7832 : throw "EXCEPT:MATHERR:ZERODIV"
7833 : endif
7834 : return a:a / a:b
7835 :endfunction
7836 :
7837 :function! Write(file)
7838 : try
7839 : execute "write" fnameescape(a:file)
7840 : catch /^Vim(write):/
7841 : throw "EXCEPT:IO(" . getcwd() . ", " . a:file . "):WRITEERR"
7842 : endtry
7843 :endfunction
7844 :
7845 :try
7846 :
7847 : " something with arithmetics and I/O
7848 :
7849 :catch /^EXCEPT:MATHERR:RANGE/
7850 : let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "")
7851 : echo "Range error in" function
7852 :
7853 :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV
7854 : echo "Math error"
7855 :
7856 :catch /^EXCEPT:IO/
7857 : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "")
7858 : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "")
7859 : if file !~ '^/'
7860 : let file = dir . "/" . file
7861 : endif
7862 : echo 'I/O error for "' . file . '"'
7863 :
7864 :catch /^EXCEPT/
7865 : echo "Unspecified error"
7866 :
7867 :endtry
7869 The exceptions raised by Vim itself (on error or when pressing CTRL-C) use
7870 a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself
7871 exceptions with the "Vim" prefix; they are reserved for Vim.
7872 Vim error exceptions are parameterized with the name of the command that
7873 failed, if known. See |catch-errors|.
7876 PECULIARITIES
7877 *except-compat*
7878 The exception handling concept requires that the command sequence causing the
7879 exception is aborted immediately and control is transferred to finally clauses
7880 and/or a catch clause.
7882 In the Vim script language there are cases where scripts and functions
7883 continue after an error: in functions without the "abort" flag or in a command
7884 after ":silent!", control flow goes to the following line, and outside
7885 functions, control flow goes to the line following the outermost ":endwhile"
7886 or ":endif". On the other hand, errors should be catchable as exceptions
7887 (thus, requiring the immediate abortion).
7889 This problem has been solved by converting errors to exceptions and using
7890 immediate abortion (if not suppressed by ":silent!") only when a try
7891 conditional is active. This is no restriction since an (error) exception can
7892 be caught only from an active try conditional. If you want an immediate
7893 termination without catching the error, just use a try conditional without
7894 catch clause. (You can cause cleanup code being executed before termination
7895 by specifying a finally clause.)
7897 When no try conditional is active, the usual abortion and continuation
7898 behavior is used instead of immediate abortion. This ensures compatibility of
7899 scripts written for Vim 6.1 and earlier.
7901 However, when sourcing an existing script that does not use exception handling
7902 commands (or when calling one of its functions) from inside an active try
7903 conditional of a new script, you might change the control flow of the existing
7904 script on error. You get the immediate abortion on error and can catch the
7905 error in the new script. If however the sourced script suppresses error
7906 messages by using the ":silent!" command (checking for errors by testing
7907 |v:errmsg| if appropriate), its execution path is not changed. The error is
7908 not converted to an exception. (See |:silent|.) So the only remaining cause
7909 where this happens is for scripts that don't care about errors and produce
7910 error messages. You probably won't want to use such code from your new
7911 scripts.
7913 *except-syntax-err*
7914 Syntax errors in the exception handling commands are never caught by any of
7915 the ":catch" commands of the try conditional they belong to. Its finally
7916 clauses, however, is executed.
7917 Example: >
7919 :try
7920 : try
7921 : throw 4711
7922 : catch /\(/
7923 : echo "in catch with syntax error"
7924 : catch
7925 : echo "inner catch-all"
7926 : finally
7927 : echo "inner finally"
7928 : endtry
7929 :catch
7930 : echo 'outer catch-all caught "' . v:exception . '"'
7931 : finally
7932 : echo "outer finally"
7933 :endtry
7935 This displays: >
7936 inner finally
7937 outer catch-all caught "Vim(catch):E54: Unmatched \("
7938 outer finally
7939 The original exception is discarded and an error exception is raised, instead.
7941 *except-single-line*
7942 The ":try", ":catch", ":finally", and ":endtry" commands can be put on
7943 a single line, but then syntax errors may make it difficult to recognize the
7944 "catch" line, thus you better avoid this.
7945 Example: >
7946 :try | unlet! foo # | catch | endtry
7947 raises an error exception for the trailing characters after the ":unlet!"
7948 argument, but does not see the ":catch" and ":endtry" commands, so that the
7949 error exception is discarded and the "E488: Trailing characters" message gets
7950 displayed.
7952 *except-several-errors*
7953 When several errors appear in a single command, the first error message is
7954 usually the most specific one and therefor converted to the error exception.
7955 Example: >
7956 echo novar
7957 causes >
7958 E121: Undefined variable: novar
7959 E15: Invalid expression: novar
7960 The value of the error exception inside try conditionals is: >
7961 Vim(echo):E121: Undefined variable: novar
7962 < *except-syntax-error*
7963 But when a syntax error is detected after a normal error in the same command,
7964 the syntax error is used for the exception being thrown.
7965 Example: >
7966 unlet novar #
7967 causes >
7968 E108: No such variable: "novar"
7969 E488: Trailing characters
7970 The value of the error exception inside try conditionals is: >
7971 Vim(unlet):E488: Trailing characters
7972 This is done because the syntax error might change the execution path in a way
7973 not intended by the user. Example: >
7974 try
7975 try | unlet novar # | catch | echo v:exception | endtry
7976 catch /.*/
7977 echo "outer catch:" v:exception
7978 endtry
7979 This displays "outer catch: Vim(unlet):E488: Trailing characters", and then
7980 a "E600: Missing :endtry" error message is given, see |except-single-line|.
7982 ==============================================================================
7983 9. Examples *eval-examples*
7985 Printing in Binary ~
7986 >
7987 :" The function Nr2Bin() returns the binary string representation of a number.
7988 :func Nr2Bin(nr)
7989 : let n = a:nr
7990 : let r = ""
7991 : while n
7992 : let r = '01'[n % 2] . r
7993 : let n = n / 2
7994 : endwhile
7995 : return r
7996 :endfunc
7998 :" The function String2Bin() converts each character in a string to a
7999 :" binary string, separated with dashes.
8000 :func String2Bin(str)
8001 : let out = ''
8002 : for ix in range(strlen(a:str))
8003 : let out = out . '-' . Nr2Bin(char2nr(a:str[ix]))
8004 : endfor
8005 : return out[1:]
8006 :endfunc
8008 Example of its use: >
8009 :echo Nr2Bin(32)
8010 result: "100000" >
8011 :echo String2Bin("32")
8012 result: "110011-110010"
8015 Sorting lines ~
8017 This example sorts lines with a specific compare function. >
8019 :func SortBuffer()
8020 : let lines = getline(1, '$')
8021 : call sort(lines, function("Strcmp"))
8022 : call setline(1, lines)
8023 :endfunction
8025 As a one-liner: >
8026 :call setline(1, sort(getline(1, '$'), function("Strcmp")))
8029 scanf() replacement ~
8030 *sscanf*
8031 There is no sscanf() function in Vim. If you need to extract parts from a
8032 line, you can use matchstr() and substitute() to do it. This example shows
8033 how to get the file name, line number and column number out of a line like
8034 "foobar.txt, 123, 45". >
8035 :" Set up the match bit
8036 :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)'
8037 :"get the part matching the whole expression
8038 :let l = matchstr(line, mx)
8039 :"get each item out of the match
8040 :let file = substitute(l, mx, '\1', '')
8041 :let lnum = substitute(l, mx, '\2', '')
8042 :let col = substitute(l, mx, '\3', '')
8044 The input is in the variable "line", the results in the variables "file",
8045 "lnum" and "col". (idea from Michael Geddes)
8048 getting the scriptnames in a Dictionary ~
8049 *scriptnames-dictionary*
8050 The |:scriptnames| command can be used to get a list of all script files that
8051 have been sourced. There is no equivalent function or variable for this
8052 (because it's rarely needed). In case you need to manipulate the list this
8053 code can be used: >
8054 " Get the output of ":scriptnames" in the scriptnames_output variable.
8055 let scriptnames_output = ''
8056 redir => scriptnames_output
8057 silent scriptnames
8058 redir END
8060 " Split the output into lines and parse each line. Add an entry to the
8061 " "scripts" dictionary.
8062 let scripts = {}
8063 for line in split(scriptnames_output, "\n")
8064 " Only do non-blank lines.
8065 if line =~ '\S'
8066 " Get the first number in the line.
8067 let nr = matchstr(line, '\d\+')
8068 " Get the file name, remove the script number " 123: ".
8069 let name = substitute(line, '.\+:\s*', '', '')
8070 " Add an item to the Dictionary
8071 let scripts[nr] = name
8072 endif
8073 endfor
8074 unlet scriptnames_output
8076 ==============================================================================
8077 10. No +eval feature *no-eval-feature*
8079 When the |+eval| feature was disabled at compile time, none of the expression
8080 evaluation commands are available. To prevent this from causing Vim scripts
8081 to generate all kinds of errors, the ":if" and ":endif" commands are still
8082 recognized, though the argument of the ":if" and everything between the ":if"
8083 and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but
8084 only if the commands are at the start of the line. The ":else" command is not
8085 recognized.
8087 Example of how to avoid executing commands when the |+eval| feature is
8088 missing: >
8090 :if 1
8091 : echo "Expression evaluation is compiled in"
8092 :else
8093 : echo "You will _never_ see this message"
8094 :endif
8096 ==============================================================================
8097 11. The sandbox *eval-sandbox* *sandbox* *E48*
8099 The 'foldexpr', 'includeexpr', 'indentexpr', 'statusline' and 'foldtext'
8100 options are evaluated in a sandbox. This means that you are protected from
8101 these expressions having nasty side effects. This gives some safety for when
8102 these options are set from a modeline. It is also used when the command from
8103 a tags file is executed and for CTRL-R = in the command line.
8104 The sandbox is also used for the |:sandbox| command.
8106 These items are not allowed in the sandbox:
8107 - changing the buffer text
8108 - defining or changing mapping, autocommands, functions, user commands
8109 - setting certain options (see |option-summary|)
8110 - setting certain v: variables (see |v:var|) *E794*
8111 - executing a shell command
8112 - reading or writing a file
8113 - jumping to another buffer or editing a file
8114 - executing Python, Perl, etc. commands
8115 This is not guaranteed 100% secure, but it should block most attacks.
8117 *:san* *:sandbox*
8118 :san[dbox] {cmd} Execute {cmd} in the sandbox. Useful to evaluate an
8119 option that may have been set from a modeline, e.g.
8120 'foldexpr'.
8122 *sandbox-option*
8123 A few options contain an expression. When this expression is evaluated it may
8124 have to be done in the sandbox to avoid a security risk. But the sandbox is
8125 restrictive, thus this only happens when the option was set from an insecure
8126 location. Insecure in this context are:
8127 - sourcing a .vimrc or .exrc in the current directory
8128 - while executing in the sandbox
8129 - value coming from a modeline
8131 Note that when in the sandbox and saving an option value and restoring it, the
8132 option will still be marked as it was set in the sandbox.
8134 ==============================================================================
8135 12. Textlock *textlock*
8137 In a few situations it is not allowed to change the text in the buffer, jump
8138 to another window and some other things that might confuse or break what Vim
8139 is currently doing. This mostly applies to things that happen when Vim is
8140 actually doing something else. For example, evaluating the 'balloonexpr' may
8141 happen any moment the mouse cursor is resting at some position.
8143 This is not allowed when the textlock is active:
8144 - changing the buffer text
8145 - jumping to another buffer or window
8146 - editing another file
8147 - closing a window or quitting Vim
8148 - etc.
8151 vim:tw=78:ts=8:ft=help:norl: