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