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