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