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