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