1*usr_41.txt* For Vim version 7.3. Last change: 2010 Jul 20 2 3 VIM USER MANUAL - by Bram Moolenaar 4 5 Write a Vim script 6 7 8The Vim script language is used for the startup vimrc file, syntax files, and 9many other things. This chapter explains the items that can be used in a Vim 10script. There are a lot of them, thus this is a long chapter. 11 12|41.1| Introduction 13|41.2| Variables 14|41.3| Expressions 15|41.4| Conditionals 16|41.5| Executing an expression 17|41.6| Using functions 18|41.7| Defining a function 19|41.8| Lists and Dictionaries 20|41.9| Exceptions 21|41.10| Various remarks 22|41.11| Writing a plugin 23|41.12| Writing a filetype plugin 24|41.13| Writing a compiler plugin 25|41.14| Writing a plugin that loads quickly 26|41.15| Writing library scripts 27|41.16| Distributing Vim scripts 28 29 Next chapter: |usr_42.txt| Add new menus 30 Previous chapter: |usr_40.txt| Make new commands 31Table of contents: |usr_toc.txt| 32 33============================================================================== 34*41.1* Introduction *vim-script-intro* *script* 35 36Your first experience with Vim scripts is the vimrc file. Vim reads it when 37it starts up and executes the commands. You can set options to values you 38prefer. And you can use any colon command in it (commands that start with a 39":"; these are sometimes referred to as Ex commands or command-line commands). 40 Syntax files are also Vim scripts. As are files that set options for a 41specific file type. A complicated macro can be defined by a separate Vim 42script file. You can think of other uses yourself. 43 44Let's start with a simple example: > 45 46 :let i = 1 47 :while i < 5 48 : echo "count is" i 49 : let i += 1 50 :endwhile 51< 52 Note: 53 The ":" characters are not really needed here. You only need to use 54 them when you type a command. In a Vim script file they can be left 55 out. We will use them here anyway to make clear these are colon 56 commands and make them stand out from Normal mode commands. 57 Note: 58 You can try out the examples by yanking the lines from the text here 59 and executing them with :@" 60 61The output of the example code is: 62 63 count is 1 ~ 64 count is 2 ~ 65 count is 3 ~ 66 count is 4 ~ 67 68In the first line the ":let" command assigns a value to a variable. The 69generic form is: > 70 71 :let {variable} = {expression} 72 73In this case the variable name is "i" and the expression is a simple value, 74the number one. 75 The ":while" command starts a loop. The generic form is: > 76 77 :while {condition} 78 : {statements} 79 :endwhile 80 81The statements until the matching ":endwhile" are executed for as long as the 82condition is true. The condition used here is the expression "i < 5". This 83is true when the variable i is smaller than five. 84 Note: 85 If you happen to write a while loop that keeps on running, you can 86 interrupt it by pressing CTRL-C (CTRL-Break on MS-Windows). 87 88The ":echo" command prints its arguments. In this case the string "count is" 89and the value of the variable i. Since i is one, this will print: 90 91 count is 1 ~ 92 93Then there is the ":let i += 1" command. This does the same thing as 94":let i = i + 1". This adds one to the variable i and assigns the new value 95to the same variable. 96 97The example was given to explain the commands, but would you really want to 98make such a loop it can be written much more compact: > 99 100 :for i in range(1, 4) 101 : echo "count is" i 102 :endfor 103 104We won't explain how |:for| and |range()| work until later. Follow the links 105if you are impatient. 106 107 108THREE KINDS OF NUMBERS 109 110Numbers can be decimal, hexadecimal or octal. A hexadecimal number starts 111with "0x" or "0X". For example "0x1f" is decimal 31. An octal number starts 112with a zero. "017" is decimal 15. Careful: don't put a zero before a decimal 113number, it will be interpreted as an octal number! 114 The ":echo" command always prints decimal numbers. Example: > 115 116 :echo 0x7f 036 117< 127 30 ~ 118 119A number is made negative with a minus sign. This also works for hexadecimal 120and octal numbers. A minus sign is also used for subtraction. Compare this 121with the previous example: > 122 123 :echo 0x7f -036 124< 97 ~ 125 126White space in an expression is ignored. However, it's recommended to use it 127for separating items, to make the expression easier to read. For example, to 128avoid the confusion with a negative number above, put a space between the 129minus sign and the following number: > 130 131 :echo 0x7f - 036 132 133============================================================================== 134*41.2* Variables 135 136A variable name consists of ASCII letters, digits and the underscore. It 137cannot start with a digit. Valid variable names are: 138 139 counter 140 _aap3 141 very_long_variable_name_with_underscores 142 FuncLength 143 LENGTH 144 145Invalid names are "foo+bar" and "6var". 146 These variables are global. To see a list of currently defined variables 147use this command: > 148 149 :let 150 151You can use global variables everywhere. This also means that when the 152variable "count" is used in one script file, it might also be used in another 153file. This leads to confusion at least, and real problems at worst. To avoid 154this, you can use a variable local to a script file by prepending "s:". For 155example, one script contains this code: > 156 157 :let s:count = 1 158 :while s:count < 5 159 : source other.vim 160 : let s:count += 1 161 :endwhile 162 163Since "s:count" is local to this script, you can be sure that sourcing the 164"other.vim" script will not change this variable. If "other.vim" also uses an 165"s:count" variable, it will be a different copy, local to that script. More 166about script-local variables here: |script-variable|. 167 168There are more kinds of variables, see |internal-variables|. The most often 169used ones are: 170 171 b:name variable local to a buffer 172 w:name variable local to a window 173 g:name global variable (also in a function) 174 v:name variable predefined by Vim 175 176 177DELETING VARIABLES 178 179Variables take up memory and show up in the output of the ":let" command. To 180delete a variable use the ":unlet" command. Example: > 181 182 :unlet s:count 183 184This deletes the script-local variable "s:count" to free up the memory it 185uses. If you are not sure if the variable exists, and don't want an error 186message when it doesn't, append !: > 187 188 :unlet! s:count 189 190When a script finishes, the local variables used there will not be 191automatically freed. The next time the script executes, it can still use the 192old value. Example: > 193 194 :if !exists("s:call_count") 195 : let s:call_count = 0 196 :endif 197 :let s:call_count = s:call_count + 1 198 :echo "called" s:call_count "times" 199 200The "exists()" function checks if a variable has already been defined. Its 201argument is the name of the variable you want to check. Not the variable 202itself! If you would do this: > 203 204 :if !exists(s:call_count) 205 206Then the value of s:call_count will be used as the name of the variable that 207exists() checks. That's not what you want. 208 The exclamation mark ! negates a value. When the value was true, it 209becomes false. When it was false, it becomes true. You can read it as "not". 210Thus "if !exists()" can be read as "if not exists()". 211 What Vim calls true is anything that is not zero. Zero is false. 212 Note: 213 Vim automatically converts a string to a number when it is looking for 214 a number. When using a string that doesn't start with a digit the 215 resulting number is zero. Thus look out for this: > 216 :if "true" 217< The "true" will be interpreted as a zero, thus as false! 218 219 220STRING VARIABLES AND CONSTANTS 221 222So far only numbers were used for the variable value. Strings can be used as 223well. Numbers and strings are the basic types of variables that Vim supports. 224The type is dynamic, it is set each time when assigning a value to the 225variable with ":let". More about types in |41.8|. 226 To assign a string value to a variable, you need to use a string constant. 227There are two types of these. First the string in double quotes: > 228 229 :let name = "peter" 230 :echo name 231< peter ~ 232 233If you want to include a double quote inside the string, put a backslash in 234front of it: > 235 236 :let name = "\"peter\"" 237 :echo name 238< "peter" ~ 239 240To avoid the need for a backslash, you can use a string in single quotes: > 241 242 :let name = '"peter"' 243 :echo name 244< "peter" ~ 245 246Inside a single-quote string all the characters are as they are. Only the 247single quote itself is special: you need to use two to get one. A backslash 248is taken literally, thus you can't use it to change the meaning of the 249character after it. 250 In double-quote strings it is possible to use special characters. Here are 251a few useful ones: 252 253 \t <Tab> 254 \n <NL>, line break 255 \r <CR>, <Enter> 256 \e <Esc> 257 \b <BS>, backspace 258 \" " 259 \\ \, backslash 260 \<Esc> <Esc> 261 \<C-W> CTRL-W 262 263The last two are just examples. The "\<name>" form can be used to include 264the special key "name". 265 See |expr-quote| for the full list of special items in a string. 266 267============================================================================== 268*41.3* Expressions 269 270Vim has a rich, yet simple way to handle expressions. You can read the 271definition here: |expression-syntax|. Here we will show the most common 272items. 273 The numbers, strings and variables mentioned above are expressions by 274themselves. Thus everywhere an expression is expected, you can use a number, 275string or variable. Other basic items in an expression are: 276 277 $NAME environment variable 278 &name option 279 @r register 280 281Examples: > 282 283 :echo "The value of 'tabstop' is" &ts 284 :echo "Your home directory is" $HOME 285 :if @a > 5 286 287The &name form can be used to save an option value, set it to a new value, 288do something and restore the old value. Example: > 289 290 :let save_ic = &ic 291 :set noic 292 :/The Start/,$delete 293 :let &ic = save_ic 294 295This makes sure the "The Start" pattern is used with the 'ignorecase' option 296off. Still, it keeps the value that the user had set. (Another way to do 297this would be to add "\C" to the pattern, see |/\C|.) 298 299 300MATHEMATICS 301 302It becomes more interesting if we combine these basic items. Let's start with 303mathematics on numbers: 304 305 a + b add 306 a - b subtract 307 a * b multiply 308 a / b divide 309 a % b modulo 310 311The usual precedence is used. Example: > 312 313 :echo 10 + 5 * 2 314< 20 ~ 315 316Grouping is done with braces. No surprises here. Example: > 317 318 :echo (10 + 5) * 2 319< 30 ~ 320 321Strings can be concatenated with ".". Example: > 322 323 :echo "foo" . "bar" 324< foobar ~ 325 326When the ":echo" command gets multiple arguments, it separates them with a 327space. In the example the argument is a single expression, thus no space is 328inserted. 329 330Borrowed from the C language is the conditional expression: 331 332 a ? b : c 333 334If "a" evaluates to true "b" is used, otherwise "c" is used. Example: > 335 336 :let i = 4 337 :echo i > 5 ? "i is big" : "i is small" 338< i is small ~ 339 340The three parts of the constructs are always evaluated first, thus you could 341see it work as: 342 343 (a) ? (b) : (c) 344 345============================================================================== 346*41.4* Conditionals 347 348The ":if" commands executes the following statements, until the matching 349":endif", only when a condition is met. The generic form is: 350 351 :if {condition} 352 {statements} 353 :endif 354 355Only when the expression {condition} evaluates to true (non-zero) will the 356{statements} be executed. These must still be valid commands. If they 357contain garbage, Vim won't be able to find the ":endif". 358 You can also use ":else". The generic form for this is: 359 360 :if {condition} 361 {statements} 362 :else 363 {statements} 364 :endif 365 366The second {statements} is only executed if the first one isn't. 367 Finally, there is ":elseif": 368 369 :if {condition} 370 {statements} 371 :elseif {condition} 372 {statements} 373 :endif 374 375This works just like using ":else" and then "if", but without the need for an 376extra ":endif". 377 A useful example for your vimrc file is checking the 'term' option and 378doing something depending upon its value: > 379 380 :if &term == "xterm" 381 : " Do stuff for xterm 382 :elseif &term == "vt100" 383 : " Do stuff for a vt100 terminal 384 :else 385 : " Do something for other terminals 386 :endif 387 388 389LOGIC OPERATIONS 390 391We already used some of them in the examples. These are the most often used 392ones: 393 394 a == b equal to 395 a != b not equal to 396 a > b greater than 397 a >= b greater than or equal to 398 a < b less than 399 a <= b less than or equal to 400 401The result is one if the condition is met and zero otherwise. An example: > 402 403 :if v:version >= 700 404 : echo "congratulations" 405 :else 406 : echo "you are using an old version, upgrade!" 407 :endif 408 409Here "v:version" is a variable defined by Vim, which has the value of the Vim 410version. 600 is for version 6.0. Version 6.1 has the value 601. This is 411very useful to write a script that works with multiple versions of Vim. 412|v:version| 413 414The logic operators work both for numbers and strings. When comparing two 415strings, the mathematical difference is used. This compares byte values, 416which may not be right for some languages. 417 When comparing a string with a number, the string is first converted to a 418number. This is a bit tricky, because when a string doesn't look like a 419number, the number zero is used. Example: > 420 421 :if 0 == "one" 422 : echo "yes" 423 :endif 424 425This will echo "yes", because "one" doesn't look like a number, thus it is 426converted to the number zero. 427 428For strings there are two more items: 429 430 a =~ b matches with 431 a !~ b does not match with 432 433The left item "a" is used as a string. The right item "b" is used as a 434pattern, like what's used for searching. Example: > 435 436 :if str =~ " " 437 : echo "str contains a space" 438 :endif 439 :if str !~ '\.$' 440 : echo "str does not end in a full stop" 441 :endif 442 443Notice the use of a single-quote string for the pattern. This is useful, 444because backslashes would need to be doubled in a double-quote string and 445patterns tend to contain many backslashes. 446 447The 'ignorecase' option is used when comparing strings. When you don't want 448that, append "#" to match case and "?" to ignore case. Thus "==?" compares 449two strings to be equal while ignoring case. And "!~#" checks if a pattern 450doesn't match, also checking the case of letters. For the full table see 451|expr-==|. 452 453 454MORE LOOPING 455 456The ":while" command was already mentioned. Two more statements can be used 457in between the ":while" and the ":endwhile": 458 459 :continue Jump back to the start of the while loop; the 460 loop continues. 461 :break Jump forward to the ":endwhile"; the loop is 462 discontinued. 463 464Example: > 465 466 :while counter < 40 467 : call do_something() 468 : if skip_flag 469 : continue 470 : endif 471 : if finished_flag 472 : break 473 : endif 474 : sleep 50m 475 :endwhile 476 477The ":sleep" command makes Vim take a nap. The "50m" specifies fifty 478milliseconds. Another example is ":sleep 4", which sleeps for four seconds. 479 480Even more looping can be done with the ":for" command, see below in |41.8|. 481 482============================================================================== 483*41.5* Executing an expression 484 485So far the commands in the script were executed by Vim directly. The 486":execute" command allows executing the result of an expression. This is a 487very powerful way to build commands and execute them. 488 An example is to jump to a tag, which is contained in a variable: > 489 490 :execute "tag " . tag_name 491 492The "." is used to concatenate the string "tag " with the value of variable 493"tag_name". Suppose "tag_name" has the value "get_cmd", then the command that 494will be executed is: > 495 496 :tag get_cmd 497 498The ":execute" command can only execute colon commands. The ":normal" command 499executes Normal mode commands. However, its argument is not an expression but 500the literal command characters. Example: > 501 502 :normal gg=G 503 504This jumps to the first line and formats all lines with the "=" operator. 505 To make ":normal" work with an expression, combine ":execute" with it. 506Example: > 507 508 :execute "normal " . normal_commands 509 510The variable "normal_commands" must contain the Normal mode commands. 511 Make sure that the argument for ":normal" is a complete command. Otherwise 512Vim will run into the end of the argument and abort the command. For example, 513if you start Insert mode, you must leave Insert mode as well. This works: > 514 515 :execute "normal Inew text \<Esc>" 516 517This inserts "new text " in the current line. Notice the use of the special 518key "\<Esc>". This avoids having to enter a real <Esc> character in your 519script. 520 521If you don't want to execute a string but evaluate it to get its expression 522value, you can use the eval() function: > 523 524 :let optname = "path" 525 :let optval = eval('&' . optname) 526 527A "&" character is prepended to "path", thus the argument to eval() is 528"&path". The result will then be the value of the 'path' option. 529 The same thing can be done with: > 530 :exe 'let optval = &' . optname 531 532============================================================================== 533*41.6* Using functions 534 535Vim defines many functions and provides a large amount of functionality that 536way. A few examples will be given in this section. You can find the whole 537list here: |functions|. 538 539A function is called with the ":call" command. The parameters are passed in 540between braces, separated by commas. Example: > 541 542 :call search("Date: ", "W") 543 544This calls the search() function, with arguments "Date: " and "W". The 545search() function uses its first argument as a search pattern and the second 546one as flags. The "W" flag means the search doesn't wrap around the end of 547the file. 548 549A function can be called in an expression. Example: > 550 551 :let line = getline(".") 552 :let repl = substitute(line, '\a', "*", "g") 553 :call setline(".", repl) 554 555The getline() function obtains a line from the current buffer. Its argument 556is a specification of the line number. In this case "." is used, which means 557the line where the cursor is. 558 The substitute() function does something similar to the ":substitute" 559command. The first argument is the string on which to perform the 560substitution. The second argument is the pattern, the third the replacement 561string. Finally, the last arguments are the flags. 562 The setline() function sets the line, specified by the first argument, to a 563new string, the second argument. In this example the line under the cursor is 564replaced with the result of the substitute(). Thus the effect of the three 565statements is equal to: > 566 567 :substitute/\a/*/g 568 569Using the functions becomes more interesting when you do more work before and 570after the substitute() call. 571 572 573FUNCTIONS *function-list* 574 575There are many functions. We will mention them here, grouped by what they are 576used for. You can find an alphabetical list here: |functions|. Use CTRL-] on 577the function name to jump to detailed help on it. 578 579String manipulation: *string-functions* 580 nr2char() get a character by its ASCII value 581 char2nr() get ASCII value of a character 582 str2nr() convert a string to a Number 583 str2float() convert a string to a Float 584 printf() format a string according to % items 585 escape() escape characters in a string with a '\' 586 shellescape() escape a string for use with a shell command 587 fnameescape() escape a file name for use with a Vim command 588 tr() translate characters from one set to another 589 strtrans() translate a string to make it printable 590 tolower() turn a string to lowercase 591 toupper() turn a string to uppercase 592 match() position where a pattern matches in a string 593 matchend() position where a pattern match ends in a string 594 matchstr() match of a pattern in a string 595 matchlist() like matchstr() and also return submatches 596 stridx() first index of a short string in a long string 597 strridx() last index of a short string in a long string 598 strlen() length of a string 599 substitute() substitute a pattern match with a string 600 submatch() get a specific match in a ":substitute" 601 strpart() get part of a string 602 expand() expand special keywords 603 iconv() convert text from one encoding to another 604 byteidx() byte index of a character in a string 605 repeat() repeat a string multiple times 606 eval() evaluate a string expression 607 608List manipulation: *list-functions* 609 get() get an item without error for wrong index 610 len() number of items in a List 611 empty() check if List is empty 612 insert() insert an item somewhere in a List 613 add() append an item to a List 614 extend() append a List to a List 615 remove() remove one or more items from a List 616 copy() make a shallow copy of a List 617 deepcopy() make a full copy of a List 618 filter() remove selected items from a List 619 map() change each List item 620 sort() sort a List 621 reverse() reverse the order of a List 622 split() split a String into a List 623 join() join List items into a String 624 range() return a List with a sequence of numbers 625 string() String representation of a List 626 call() call a function with List as arguments 627 index() index of a value in a List 628 max() maximum value in a List 629 min() minimum value in a List 630 count() count number of times a value appears in a List 631 repeat() repeat a List multiple times 632 633Dictionary manipulation: *dict-functions* 634 get() get an entry without an error for a wrong key 635 len() number of entries in a Dictionary 636 has_key() check whether a key appears in a Dictionary 637 empty() check if Dictionary is empty 638 remove() remove an entry from a Dictionary 639 extend() add entries from one Dictionary to another 640 filter() remove selected entries from a Dictionary 641 map() change each Dictionary entry 642 keys() get List of Dictionary keys 643 values() get List of Dictionary values 644 items() get List of Dictionary key-value pairs 645 copy() make a shallow copy of a Dictionary 646 deepcopy() make a full copy of a Dictionary 647 string() String representation of a Dictionary 648 max() maximum value in a Dictionary 649 min() minimum value in a Dictionary 650 count() count number of times a value appears 651 652Floating point computation: *float-functions* 653 float2nr() convert Float to Number 654 abs() absolute value (also works for Number) 655 round() round off 656 ceil() round up 657 floor() round down 658 trunc() remove value after decimal point 659 log10() logarithm to base 10 660 pow() value of x to the exponent y 661 sqrt() square root 662 sin() sine 663 cos() cosine 664 atan() arc tangent 665 666Variables: *var-functions* 667 type() type of a variable 668 islocked() check if a variable is locked 669 function() get a Funcref for a function name 670 getbufvar() get a variable value from a specific buffer 671 setbufvar() set a variable in a specific buffer 672 getwinvar() get a variable from specific window 673 gettabvar() get a variable from specific tab page 674 gettabwinvar() get a variable from specific window & tab page 675 setwinvar() set a variable in a specific window 676 settabvar() set a variable in a specific tab page 677 settabwinvar() set a variable in a specific window & tab page 678 garbagecollect() possibly free memory 679 680Cursor and mark position: *cursor-functions* *mark-functions* 681 col() column number of the cursor or a mark 682 virtcol() screen column of the cursor or a mark 683 line() line number of the cursor or mark 684 wincol() window column number of the cursor 685 winline() window line number of the cursor 686 cursor() position the cursor at a line/column 687 getpos() get position of cursor, mark, etc. 688 setpos() set position of cursor, mark, etc. 689 byte2line() get line number at a specific byte count 690 line2byte() byte count at a specific line 691 diff_filler() get the number of filler lines above a line 692 693Working with text in the current buffer: *text-functions* 694 getline() get a line or list of lines from the buffer 695 setline() replace a line in the buffer 696 append() append line or list of lines in the buffer 697 indent() indent of a specific line 698 cindent() indent according to C indenting 699 lispindent() indent according to Lisp indenting 700 nextnonblank() find next non-blank line 701 prevnonblank() find previous non-blank line 702 search() find a match for a pattern 703 searchpos() find a match for a pattern 704 searchpair() find the other end of a start/skip/end 705 searchpairpos() find the other end of a start/skip/end 706 searchdecl() search for the declaration of a name 707 708 *system-functions* *file-functions* 709System functions and manipulation of files: 710 glob() expand wildcards 711 globpath() expand wildcards in a number of directories 712 findfile() find a file in a list of directories 713 finddir() find a directory in a list of directories 714 resolve() find out where a shortcut points to 715 fnamemodify() modify a file name 716 pathshorten() shorten directory names in a path 717 simplify() simplify a path without changing its meaning 718 executable() check if an executable program exists 719 filereadable() check if a file can be read 720 filewritable() check if a file can be written to 721 getfperm() get the permissions of a file 722 getftype() get the kind of a file 723 isdirectory() check if a directory exists 724 getfsize() get the size of a file 725 getcwd() get the current working directory 726 haslocaldir() check if current window used |:lcd| 727 tempname() get the name of a temporary file 728 mkdir() create a new directory 729 delete() delete a file 730 rename() rename a file 731 system() get the result of a shell command 732 hostname() name of the system 733 readfile() read a file into a List of lines 734 writefile() write a List of lines into a file 735 736Date and Time: *date-functions* *time-functions* 737 getftime() get last modification time of a file 738 localtime() get current time in seconds 739 strftime() convert time to a string 740 reltime() get the current or elapsed time accurately 741 reltimestr() convert reltime() result to a string 742 743 *buffer-functions* *window-functions* *arg-functions* 744Buffers, windows and the argument list: 745 argc() number of entries in the argument list 746 argidx() current position in the argument list 747 argv() get one entry from the argument list 748 bufexists() check if a buffer exists 749 buflisted() check if a buffer exists and is listed 750 bufloaded() check if a buffer exists and is loaded 751 bufname() get the name of a specific buffer 752 bufnr() get the buffer number of a specific buffer 753 tabpagebuflist() return List of buffers in a tab page 754 tabpagenr() get the number of a tab page 755 tabpagewinnr() like winnr() for a specified tab page 756 winnr() get the window number for the current window 757 bufwinnr() get the window number of a specific buffer 758 winbufnr() get the buffer number of a specific window 759 getbufline() get a list of lines from the specified buffer 760 761Command line: *command-line-functions* 762 getcmdline() get the current command line 763 getcmdpos() get position of the cursor in the command line 764 setcmdpos() set position of the cursor in the command line 765 getcmdtype() return the current command-line type 766 767Quickfix and location lists: *quickfix-functions* 768 getqflist() list of quickfix errors 769 setqflist() modify a quickfix list 770 getloclist() list of location list items 771 setloclist() modify a location list 772 773Insert mode completion: *completion-functions* 774 complete() set found matches 775 complete_add() add to found matches 776 complete_check() check if completion should be aborted 777 pumvisible() check if the popup menu is displayed 778 779Folding: *folding-functions* 780 foldclosed() check for a closed fold at a specific line 781 foldclosedend() like foldclosed() but return the last line 782 foldlevel() check for the fold level at a specific line 783 foldtext() generate the line displayed for a closed fold 784 foldtextresult() get the text displayed for a closed fold 785 786Syntax and highlighting: *syntax-functions* *highlighting-functions* 787 clearmatches() clear all matches defined by |matchadd()| and 788 the |:match| commands 789 getmatches() get all matches defined by |matchadd()| and 790 the |:match| commands 791 hlexists() check if a highlight group exists 792 hlID() get ID of a highlight group 793 synID() get syntax ID at a specific position 794 synIDattr() get a specific attribute of a syntax ID 795 synIDtrans() get translated syntax ID 796 diff_hlID() get highlight ID for diff mode at a position 797 matchadd() define a pattern to highlight (a "match") 798 matcharg() get info about |:match| arguments 799 matchdelete() delete a match defined by |matchadd()| or a 800 |:match| command 801 setmatches() restore a list of matches saved by 802 |getmatches()| 803 804Spelling: *spell-functions* 805 spellbadword() locate badly spelled word at or after cursor 806 spellsuggest() return suggested spelling corrections 807 soundfold() return the sound-a-like equivalent of a word 808 809History: *history-functions* 810 histadd() add an item to a history 811 histdel() delete an item from a history 812 histget() get an item from a history 813 histnr() get highest index of a history list 814 815Interactive: *interactive-functions* 816 browse() put up a file requester 817 browsedir() put up a directory requester 818 confirm() let the user make a choice 819 getchar() get a character from the user 820 getcharmod() get modifiers for the last typed character 821 feedkeys() put characters in the typeahead queue 822 input() get a line from the user 823 inputlist() let the user pick an entry from a list 824 inputsecret() get a line from the user without showing it 825 inputdialog() get a line from the user in a dialog 826 inputsave() save and clear typeahead 827 inputrestore() restore typeahead 828 829GUI: *gui-functions* 830 getfontname() get name of current font being used 831 getwinposx() X position of the GUI Vim window 832 getwinposy() Y position of the GUI Vim window 833 834Vim server: *server-functions* 835 serverlist() return the list of server names 836 remote_send() send command characters to a Vim server 837 remote_expr() evaluate an expression in a Vim server 838 server2client() send a reply to a client of a Vim server 839 remote_peek() check if there is a reply from a Vim server 840 remote_read() read a reply from a Vim server 841 foreground() move the Vim window to the foreground 842 remote_foreground() move the Vim server window to the foreground 843 844Window size and position: *window-size-functions* 845 winheight() get height of a specific window 846 winwidth() get width of a specific window 847 winrestcmd() return command to restore window sizes 848 winsaveview() get view of current window 849 winrestview() restore saved view of current window 850 851Various: *various-functions* 852 mode() get current editing mode 853 visualmode() last visual mode used 854 hasmapto() check if a mapping exists 855 mapcheck() check if a matching mapping exists 856 maparg() get rhs of a mapping 857 exists() check if a variable, function, etc. exists 858 has() check if a feature is supported in Vim 859 changenr() return number of most recent change 860 cscope_connection() check if a cscope connection exists 861 did_filetype() check if a FileType autocommand was used 862 eventhandler() check if invoked by an event handler 863 getpid() get process ID of Vim 864 865 libcall() call a function in an external library 866 libcallnr() idem, returning a number 867 868 getreg() get contents of a register 869 getregtype() get type of a register 870 setreg() set contents and type of a register 871 872 taglist() get list of matching tags 873 tagfiles() get a list of tags files 874 875 mzeval() evaluate |MzScheme| expression 876 877============================================================================== 878*41.7* Defining a function 879 880Vim enables you to define your own functions. The basic function declaration 881begins as follows: > 882 883 :function {name}({var1}, {var2}, ...) 884 : {body} 885 :endfunction 886< 887 Note: 888 Function names must begin with a capital letter. 889 890Let's define a short function to return the smaller of two numbers. It starts 891with this line: > 892 893 :function Min(num1, num2) 894 895This tells Vim that the function is named "Min" and it takes two arguments: 896"num1" and "num2". 897 The first thing you need to do is to check to see which number is smaller: 898 > 899 : if a:num1 < a:num2 900 901The special prefix "a:" tells Vim that the variable is a function argument. 902Let's assign the variable "smaller" the value of the smallest number: > 903 904 : if a:num1 < a:num2 905 : let smaller = a:num1 906 : else 907 : let smaller = a:num2 908 : endif 909 910The variable "smaller" is a local variable. Variables used inside a function 911are local unless prefixed by something like "g:", "a:", or "s:". 912 913 Note: 914 To access a global variable from inside a function you must prepend 915 "g:" to it. Thus "g:today" inside a function is used for the global 916 variable "today", and "today" is another variable, local to the 917 function. 918 919You now use the ":return" statement to return the smallest number to the user. 920Finally, you end the function: > 921 922 : return smaller 923 :endfunction 924 925The complete function definition is as follows: > 926 927 :function Min(num1, num2) 928 : if a:num1 < a:num2 929 : let smaller = a:num1 930 : else 931 : let smaller = a:num2 932 : endif 933 : return smaller 934 :endfunction 935 936For people who like short functions, this does the same thing: > 937 938 :function Min(num1, num2) 939 : if a:num1 < a:num2 940 : return a:num1 941 : endif 942 : return a:num2 943 :endfunction 944 945A user defined function is called in exactly the same way as a built-in 946function. Only the name is different. The Min function can be used like 947this: > 948 949 :echo Min(5, 8) 950 951Only now will the function be executed and the lines be interpreted by Vim. 952If there are mistakes, like using an undefined variable or function, you will 953now get an error message. When defining the function these errors are not 954detected. 955 956When a function reaches ":endfunction" or ":return" is used without an 957argument, the function returns zero. 958 959To redefine a function that already exists, use the ! for the ":function" 960command: > 961 962 :function! Min(num1, num2, num3) 963 964 965USING A RANGE 966 967The ":call" command can be given a line range. This can have one of two 968meanings. When a function has been defined with the "range" keyword, it will 969take care of the line range itself. 970 The function will be passed the variables "a:firstline" and "a:lastline". 971These will have the line numbers from the range the function was called with. 972Example: > 973 974 :function Count_words() range 975 : let lnum = a:firstline 976 : let n = 0 977 : while lnum <= a:lastline 978 : let n = n + len(split(getline(lnum))) 979 : let lnum = lnum + 1 980 : endwhile 981 : echo "found " . n . " words" 982 :endfunction 983 984You can call this function with: > 985 986 :10,30call Count_words() 987 988It will be executed once and echo the number of words. 989 The other way to use a line range is by defining a function without the 990"range" keyword. The function will be called once for every line in the 991range, with the cursor in that line. Example: > 992 993 :function Number() 994 : echo "line " . line(".") . " contains: " . getline(".") 995 :endfunction 996 997If you call this function with: > 998 999 :10,15call Number() 1000 1001The function will be called six times. 1002 1003 1004VARIABLE NUMBER OF ARGUMENTS 1005 1006Vim enables you to define functions that have a variable number of arguments. 1007The following command, for instance, defines a function that must have 1 1008argument (start) and can have up to 20 additional arguments: > 1009 1010 :function Show(start, ...) 1011 1012The variable "a:1" contains the first optional argument, "a:2" the second, and 1013so on. The variable "a:0" contains the number of extra arguments. 1014 For example: > 1015 1016 :function Show(start, ...) 1017 : echohl Title 1018 : echo "Show is " . a:start 1019 : echohl None 1020 : let index = 1 1021 : while index <= a:0 1022 : echo " Arg " . index . " is " . a:{index} 1023 : let index = index + 1 1024 : endwhile 1025 : echo "" 1026 :endfunction 1027 1028This uses the ":echohl" command to specify the highlighting used for the 1029following ":echo" command. ":echohl None" stops it again. The ":echon" 1030command works like ":echo", but doesn't output a line break. 1031 1032You can also use the a:000 variable, it is a List of all the "..." arguments. 1033See |a:000|. 1034 1035 1036LISTING FUNCTIONS 1037 1038The ":function" command lists the names and arguments of all user-defined 1039functions: > 1040 1041 :function 1042< function Show(start, ...) ~ 1043 function GetVimIndent() ~ 1044 function SetSyn(name) ~ 1045 1046To see what a function does, use its name as an argument for ":function": > 1047 1048 :function SetSyn 1049< 1 if &syntax == '' ~ 1050 2 let &syntax = a:name ~ 1051 3 endif ~ 1052 endfunction ~ 1053 1054 1055DEBUGGING 1056 1057The line number is useful for when you get an error message or when debugging. 1058See |debug-scripts| about debugging mode. 1059 You can also set the 'verbose' option to 12 or higher to see all function 1060calls. Set it to 15 or higher to see every executed line. 1061 1062 1063DELETING A FUNCTION 1064 1065To delete the Show() function: > 1066 1067 :delfunction Show 1068 1069You get an error when the function doesn't exist. 1070 1071 1072FUNCTION REFERENCES 1073 1074Sometimes it can be useful to have a variable point to one function or 1075another. You can do it with the function() function. It turns the name of a 1076function into a reference: > 1077 1078 :let result = 0 " or 1 1079 :function! Right() 1080 : return 'Right!' 1081 :endfunc 1082 :function! Wrong() 1083 : return 'Wrong!' 1084 :endfunc 1085 : 1086 :if result == 1 1087 : let Afunc = function('Right') 1088 :else 1089 : let Afunc = function('Wrong') 1090 :endif 1091 :echo call(Afunc, []) 1092< Wrong! ~ 1093 1094Note that the name of a variable that holds a function reference must start 1095with a capital. Otherwise it could be confused with the name of a builtin 1096function. 1097 The way to invoke a function that a variable refers to is with the call() 1098function. Its first argument is the function reference, the second argument 1099is a List with arguments. 1100 1101Function references are most useful in combination with a Dictionary, as is 1102explained in the next section. 1103 1104============================================================================== 1105*41.8* Lists and Dictionaries 1106 1107So far we have used the basic types String and Number. Vim also supports two 1108composite types: List and Dictionary. 1109 1110A List is an ordered sequence of things. The things can be any kind of value, 1111thus you can make a List of numbers, a List of Lists and even a List of mixed 1112items. To create a List with three strings: > 1113 1114 :let alist = ['aap', 'mies', 'noot'] 1115 1116The List items are enclosed in square brackets and separated by commas. To 1117create an empty List: > 1118 1119 :let alist = [] 1120 1121You can add items to a List with the add() function: > 1122 1123 :let alist = [] 1124 :call add(alist, 'foo') 1125 :call add(alist, 'bar') 1126 :echo alist 1127< ['foo', 'bar'] ~ 1128 1129List concatenation is done with +: > 1130 1131 :echo alist + ['foo', 'bar'] 1132< ['foo', 'bar', 'foo', 'bar'] ~ 1133 1134Or, if you want to extend a List directly: > 1135 1136 :let alist = ['one'] 1137 :call extend(alist, ['two', 'three']) 1138 :echo alist 1139< ['one', 'two', 'three'] ~ 1140 1141Notice that using add() will have a different effect: > 1142 1143 :let alist = ['one'] 1144 :call add(alist, ['two', 'three']) 1145 :echo alist 1146< ['one', ['two', 'three']] ~ 1147 1148The second argument of add() is added as a single item. 1149 1150 1151FOR LOOP 1152 1153One of the nice things you can do with a List is iterate over it: > 1154 1155 :let alist = ['one', 'two', 'three'] 1156 :for n in alist 1157 : echo n 1158 :endfor 1159< one ~ 1160 two ~ 1161 three ~ 1162 1163This will loop over each element in List "alist", assigning the value to 1164variable "n". The generic form of a for loop is: > 1165 1166 :for {varname} in {listexpression} 1167 : {commands} 1168 :endfor 1169 1170To loop a certain number of times you need a List of a specific length. The 1171range() function creates one for you: > 1172 1173 :for a in range(3) 1174 : echo a 1175 :endfor 1176< 0 ~ 1177 1 ~ 1178 2 ~ 1179 1180Notice that the first item of the List that range() produces is zero, thus the 1181last item is one less than the length of the list. 1182 You can also specify the maximum value, the stride and even go backwards: > 1183 1184 :for a in range(8, 4, -2) 1185 : echo a 1186 :endfor 1187< 8 ~ 1188 6 ~ 1189 4 ~ 1190 1191A more useful example, looping over lines in the buffer: > 1192 1193 :for line in getline(1, 20) 1194 : if line =~ "Date: " 1195 : echo matchstr(line, 'Date: \zs.*') 1196 : endif 1197 :endfor 1198 1199This looks into lines 1 to 20 (inclusive) and echoes any date found in there. 1200 1201 1202DICTIONARIES 1203 1204A Dictionary stores key-value pairs. You can quickly lookup a value if you 1205know the key. A Dictionary is created with curly braces: > 1206 1207 :let uk2nl = {'one': 'een', 'two': 'twee', 'three': 'drie'} 1208 1209Now you can lookup words by putting the key in square brackets: > 1210 1211 :echo uk2nl['two'] 1212< twee ~ 1213 1214The generic form for defining a Dictionary is: > 1215 1216 {<key> : <value>, ...} 1217 1218An empty Dictionary is one without any keys: > 1219 1220 {} 1221 1222The possibilities with Dictionaries are numerous. There are various functions 1223for them as well. For example, you can obtain a list of the keys and loop 1224over them: > 1225 1226 :for key in keys(uk2nl) 1227 : echo key 1228 :endfor 1229< three ~ 1230 one ~ 1231 two ~ 1232 1233You will notice the keys are not ordered. You can sort the list to get a 1234specific order: > 1235 1236 :for key in sort(keys(uk2nl)) 1237 : echo key 1238 :endfor 1239< one ~ 1240 three ~ 1241 two ~ 1242 1243But you can never get back the order in which items are defined. For that you 1244need to use a List, it stores items in an ordered sequence. 1245 1246 1247DICTIONARY FUNCTIONS 1248 1249The items in a Dictionary can normally be obtained with an index in square 1250brackets: > 1251 1252 :echo uk2nl['one'] 1253< een ~ 1254 1255A method that does the same, but without so many punctuation characters: > 1256 1257 :echo uk2nl.one 1258< een ~ 1259 1260This only works for a key that is made of ASCII letters, digits and the 1261underscore. You can also assign a new value this way: > 1262 1263 :let uk2nl.four = 'vier' 1264 :echo uk2nl 1265< {'three': 'drie', 'four': 'vier', 'one': 'een', 'two': 'twee'} ~ 1266 1267And now for something special: you can directly define a function and store a 1268reference to it in the dictionary: > 1269 1270 :function uk2nl.translate(line) dict 1271 : return join(map(split(a:line), 'get(self, v:val, "???")')) 1272 :endfunction 1273 1274Let's first try it out: > 1275 1276 :echo uk2nl.translate('three two five one') 1277< drie twee ??? een ~ 1278 1279The first special thing you notice is the "dict" at the end of the ":function" 1280line. This marks the function as being used from a Dictionary. The "self" 1281local variable will then refer to that Dictionary. 1282 Now let's break up the complicated return command: > 1283 1284 split(a:line) 1285 1286The split() function takes a string, chops it into white separated words 1287and returns a list with these words. Thus in the example it returns: > 1288 1289 :echo split('three two five one') 1290< ['three', 'two', 'five', 'one'] ~ 1291 1292This list is the first argument to the map() function. This will go through 1293the list, evaluating its second argument with "v:val" set to the value of each 1294item. This is a shortcut to using a for loop. This command: > 1295 1296 :let alist = map(split(a:line), 'get(self, v:val, "???")') 1297 1298Is equivalent to: > 1299 1300 :let alist = split(a:line) 1301 :for idx in range(len(alist)) 1302 : let alist[idx] = get(self, alist[idx], "???") 1303 :endfor 1304 1305The get() function checks if a key is present in a Dictionary. If it is, then 1306the value is retrieved. If it isn't, then the default value is returned, in 1307the example it's '???'. This is a convenient way to handle situations where a 1308key may not be present and you don't want an error message. 1309 1310The join() function does the opposite of split(): it joins together a list of 1311words, putting a space in between. 1312 This combination of split(), map() and join() is a nice way to filter a line 1313of words in a very compact way. 1314 1315 1316OBJECT ORIENTED PROGRAMMING 1317 1318Now that you can put both values and functions in a Dictionary, you can 1319actually use a Dictionary like an object. 1320 Above we used a Dictionary for translating Dutch to English. We might want 1321to do the same for other languages. Let's first make an object (aka 1322Dictionary) that has the translate function, but no words to translate: > 1323 1324 :let transdict = {} 1325 :function transdict.translate(line) dict 1326 : return join(map(split(a:line), 'get(self.words, v:val, "???")')) 1327 :endfunction 1328 1329It's slightly different from the function above, using 'self.words' to lookup 1330word translations. But we don't have a self.words. Thus you could call this 1331an abstract class. 1332 1333Now we can instantiate a Dutch translation object: > 1334 1335 :let uk2nl = copy(transdict) 1336 :let uk2nl.words = {'one': 'een', 'two': 'twee', 'three': 'drie'} 1337 :echo uk2nl.translate('three one') 1338< drie een ~ 1339 1340And a German translator: > 1341 1342 :let uk2de = copy(transdict) 1343 :let uk2de.words = {'one': 'ein', 'two': 'zwei', 'three': 'drei'} 1344 :echo uk2de.translate('three one') 1345< drei ein ~ 1346 1347You see that the copy() function is used to make a copy of the "transdict" 1348Dictionary and then the copy is changed to add the words. The original 1349remains the same, of course. 1350 1351Now you can go one step further, and use your preferred translator: > 1352 1353 :if $LANG =~ "de" 1354 : let trans = uk2de 1355 :else 1356 : let trans = uk2nl 1357 :endif 1358 :echo trans.translate('one two three') 1359< een twee drie ~ 1360 1361Here "trans" refers to one of the two objects (Dictionaries). No copy is 1362made. More about List and Dictionary identity can be found at |list-identity| 1363and |dict-identity|. 1364 1365Now you might use a language that isn't supported. You can overrule the 1366translate() function to do nothing: > 1367 1368 :let uk2uk = copy(transdict) 1369 :function! uk2uk.translate(line) 1370 : return a:line 1371 :endfunction 1372 :echo uk2uk.translate('three one wladiwostok') 1373< three one wladiwostok ~ 1374 1375Notice that a ! was used to overwrite the existing function reference. Now 1376use "uk2uk" when no recognized language is found: > 1377 1378 :if $LANG =~ "de" 1379 : let trans = uk2de 1380 :elseif $LANG =~ "nl" 1381 : let trans = uk2nl 1382 :else 1383 : let trans = uk2uk 1384 :endif 1385 :echo trans.translate('one two three') 1386< one two three ~ 1387 1388For further reading see |Lists| and |Dictionaries|. 1389 1390============================================================================== 1391*41.9* Exceptions 1392 1393Let's start with an example: > 1394 1395 :try 1396 : read ~/templates/pascal.tmpl 1397 :catch /E484:/ 1398 : echo "Sorry, the Pascal template file cannot be found." 1399 :endtry 1400 1401The ":read" command will fail if the file does not exist. Instead of 1402generating an error message, this code catches the error and gives the user a 1403nice message instead. 1404 1405For the commands in between ":try" and ":endtry" errors are turned into 1406exceptions. An exception is a string. In the case of an error the string 1407contains the error message. And every error message has a number. In this 1408case, the error we catch contains "E484:". This number is guaranteed to stay 1409the same (the text may change, e.g., it may be translated). 1410 1411When the ":read" command causes another error, the pattern "E484:" will not 1412match in it. Thus this exception will not be caught and result in the usual 1413error message. 1414 1415You might be tempted to do this: > 1416 1417 :try 1418 : read ~/templates/pascal.tmpl 1419 :catch 1420 : echo "Sorry, the Pascal template file cannot be found." 1421 :endtry 1422 1423This means all errors are caught. But then you will not see errors that are 1424useful, such as "E21: Cannot make changes, 'modifiable' is off". 1425 1426Another useful mechanism is the ":finally" command: > 1427 1428 :let tmp = tempname() 1429 :try 1430 : exe ".,$write " . tmp 1431 : exe "!filter " . tmp 1432 : .,$delete 1433 : exe "$read " . tmp 1434 :finally 1435 : call delete(tmp) 1436 :endtry 1437 1438This filters the lines from the cursor until the end of the file through the 1439"filter" command, which takes a file name argument. No matter if the 1440filtering works, something goes wrong in between ":try" and ":finally" or the 1441user cancels the filtering by pressing CTRL-C, the "call delete(tmp)" is 1442always executed. This makes sure you don't leave the temporary file behind. 1443 1444More information about exception handling can be found in the reference 1445manual: |exception-handling|. 1446 1447============================================================================== 1448*41.10* Various remarks 1449 1450Here is a summary of items that apply to Vim scripts. They are also mentioned 1451elsewhere, but form a nice checklist. 1452 1453The end-of-line character depends on the system. For Unix a single <NL> 1454character is used. For MS-DOS, Windows, OS/2 and the like, <CR><LF> is used. 1455This is important when using mappings that end in a <CR>. See |:source_crnl|. 1456 1457 1458WHITE SPACE 1459 1460Blank lines are allowed and ignored. 1461 1462Leading whitespace characters (blanks and TABs) are always ignored. The 1463whitespaces between parameters (e.g. between the 'set' and the 'cpoptions' in 1464the example below) are reduced to one blank character and plays the role of a 1465separator, the whitespaces after the last (visible) character may or may not 1466be ignored depending on the situation, see below. 1467 1468For a ":set" command involving the "=" (equal) sign, such as in: > 1469 1470 :set cpoptions =aABceFst 1471 1472the whitespace immediately before the "=" sign is ignored. But there can be 1473no whitespace after the "=" sign! 1474 1475To include a whitespace character in the value of an option, it must be 1476escaped by a "\" (backslash) as in the following example: > 1477 1478 :set tags=my\ nice\ file 1479 1480The same example written as > 1481 1482 :set tags=my nice file 1483 1484will issue an error, because it is interpreted as: > 1485 1486 :set tags=my 1487 :set nice 1488 :set file 1489 1490 1491COMMENTS 1492 1493The character " (the double quote mark) starts a comment. Everything after 1494and including this character until the end-of-line is considered a comment and 1495is ignored, except for commands that don't consider comments, as shown in 1496examples below. A comment can start on any character position on the line. 1497 1498There is a little "catch" with comments for some commands. Examples: > 1499 1500 :abbrev dev development " shorthand 1501 :map <F3> o#include " insert include 1502 :execute cmd " do it 1503 :!ls *.c " list C files 1504 1505The abbreviation 'dev' will be expanded to 'development " shorthand'. The 1506mapping of <F3> will actually be the whole line after the 'o# ....' including 1507the '" insert include'. The "execute" command will give an error. The "!" 1508command will send everything after it to the shell, causing an error for an 1509unmatched '"' character. 1510 There can be no comment after ":map", ":abbreviate", ":execute" and "!" 1511commands (there are a few more commands with this restriction). For the 1512":map", ":abbreviate" and ":execute" commands there is a trick: > 1513 1514 :abbrev dev development|" shorthand 1515 :map <F3> o#include|" insert include 1516 :execute cmd |" do it 1517 1518With the '|' character the command is separated from the next one. And that 1519next command is only a comment. For the last command you need to do two 1520things: |:execute| and use '|': > 1521 :exe '!ls *.c' |" list C files 1522 1523Notice that there is no white space before the '|' in the abbreviation and 1524mapping. For these commands, any character until the end-of-line or '|' is 1525included. As a consequence of this behavior, you don't always see that 1526trailing whitespace is included: > 1527 1528 :map <F4> o#include 1529 1530To spot these problems, you can set the 'list' option when editing vimrc 1531files. 1532 1533For Unix there is one special way to comment a line, that allows making a Vim 1534script executable: > 1535 #!/usr/bin/env vim -S 1536 echo "this is a Vim script" 1537 quit 1538 1539The "#" command by itself lists a line with the line number. Adding an 1540exclamation mark changes it into doing nothing, so that you can add the shell 1541command to execute the rest of the file. |:#!| |-S| 1542 1543 1544PITFALLS 1545 1546Even bigger problem arises in the following example: > 1547 1548 :map ,ab o#include 1549 :unmap ,ab 1550 1551Here the unmap command will not work, because it tries to unmap ",ab ". This 1552does not exist as a mapped sequence. An error will be issued, which is very 1553hard to identify, because the ending whitespace character in ":unmap ,ab " is 1554not visible. 1555 1556And this is the same as what happens when one uses a comment after an 'unmap' 1557command: > 1558 1559 :unmap ,ab " comment 1560 1561Here the comment part will be ignored. However, Vim will try to unmap 1562',ab ', which does not exist. Rewrite it as: > 1563 1564 :unmap ,ab| " comment 1565 1566 1567RESTORING THE VIEW 1568 1569Sometimes you want to make a change and go back to where cursor was. 1570Restoring the relative position would also be nice, so that the same line 1571appears at the top of the window. 1572 This example yanks the current line, puts it above the first line in the 1573file and then restores the view: > 1574 1575 map ,p ma"aYHmbgg"aP`bzt`a 1576 1577What this does: > 1578 ma"aYHmbgg"aP`bzt`a 1579< ma set mark a at cursor position 1580 "aY yank current line into register a 1581 Hmb go to top line in window and set mark b there 1582 gg go to first line in file 1583 "aP put the yanked line above it 1584 `b go back to top line in display 1585 zt position the text in the window as before 1586 `a go back to saved cursor position 1587 1588 1589PACKAGING 1590 1591To avoid your function names to interfere with functions that you get from 1592others, use this scheme: 1593- Prepend a unique string before each function name. I often use an 1594 abbreviation. For example, "OW_" is used for the option window functions. 1595- Put the definition of your functions together in a file. Set a global 1596 variable to indicate that the functions have been loaded. When sourcing the 1597 file again, first unload the functions. 1598Example: > 1599 1600 " This is the XXX package 1601 1602 if exists("XXX_loaded") 1603 delfun XXX_one 1604 delfun XXX_two 1605 endif 1606 1607 function XXX_one(a) 1608 ... body of function ... 1609 endfun 1610 1611 function XXX_two(b) 1612 ... body of function ... 1613 endfun 1614 1615 let XXX_loaded = 1 1616 1617============================================================================== 1618*41.11* Writing a plugin *write-plugin* 1619 1620You can write a Vim script in such a way that many people can use it. This is 1621called a plugin. Vim users can drop your script in their plugin directory and 1622use its features right away |add-plugin|. 1623 1624There are actually two types of plugins: 1625 1626 global plugins: For all types of files. 1627filetype plugins: Only for files of a specific type. 1628 1629In this section the first type is explained. Most items are also relevant for 1630writing filetype plugins. The specifics for filetype plugins are in the next 1631section |write-filetype-plugin|. 1632 1633 1634NAME 1635 1636First of all you must choose a name for your plugin. The features provided 1637by the plugin should be clear from its name. And it should be unlikely that 1638someone else writes a plugin with the same name but which does something 1639different. And please limit the name to 8 characters, to avoid problems on 1640old Windows systems. 1641 1642A script that corrects typing mistakes could be called "typecorr.vim". We 1643will use it here as an example. 1644 1645For the plugin to work for everybody, it should follow a few guidelines. This 1646will be explained step-by-step. The complete example plugin is at the end. 1647 1648 1649BODY 1650 1651Let's start with the body of the plugin, the lines that do the actual work: > 1652 1653 14 iabbrev teh the 1654 15 iabbrev otehr other 1655 16 iabbrev wnat want 1656 17 iabbrev synchronisation 1657 18 \ synchronization 1658 19 let s:count = 4 1659 1660The actual list should be much longer, of course. 1661 1662The line numbers have only been added to explain a few things, don't put them 1663in your plugin file! 1664 1665 1666HEADER 1667 1668You will probably add new corrections to the plugin and soon have several 1669versions laying around. And when distributing this file, people will want to 1670know who wrote this wonderful plugin and where they can send remarks. 1671Therefore, put a header at the top of your plugin: > 1672 1673 1 " Vim global plugin for correcting typing mistakes 1674 2 " Last Change: 2000 Oct 15 1675 3 " Maintainer: Bram Moolenaar <Bram@vim.org> 1676 1677About copyright and licensing: Since plugins are very useful and it's hardly 1678worth restricting their distribution, please consider making your plugin 1679either public domain or use the Vim |license|. A short note about this near 1680the top of the plugin should be sufficient. Example: > 1681 1682 4 " License: This file is placed in the public domain. 1683 1684 1685LINE CONTINUATION, AVOIDING SIDE EFFECTS *use-cpo-save* 1686 1687In line 18 above, the line-continuation mechanism is used |line-continuation|. 1688Users with 'compatible' set will run into trouble here, they will get an error 1689message. We can't just reset 'compatible', because that has a lot of side 1690effects. To avoid this, we will set the 'cpoptions' option to its Vim default 1691value and restore it later. That will allow the use of line-continuation and 1692make the script work for most people. It is done like this: > 1693 1694 11 let s:save_cpo = &cpo 1695 12 set cpo&vim 1696 .. 1697 42 let &cpo = s:save_cpo 1698 1699We first store the old value of 'cpoptions' in the s:save_cpo variable. At 1700the end of the plugin this value is restored. 1701 1702Notice that a script-local variable is used |s:var|. A global variable could 1703already be in use for something else. Always use script-local variables for 1704things that are only used in the script. 1705 1706 1707NOT LOADING 1708 1709It's possible that a user doesn't always want to load this plugin. Or the 1710system administrator has dropped it in the system-wide plugin directory, but a 1711user has his own plugin he wants to use. Then the user must have a chance to 1712disable loading this specific plugin. This will make it possible: > 1713 1714 6 if exists("g:loaded_typecorr") 1715 7 finish 1716 8 endif 1717 9 let g:loaded_typecorr = 1 1718 1719This also avoids that when the script is loaded twice it would cause error 1720messages for redefining functions and cause trouble for autocommands that are 1721added twice. 1722 1723The name is recommended to start with "loaded_" and then the file name of the 1724plugin, literally. The "g:" is prepended just to avoid mistakes when using 1725the variable in a function (without "g:" it would be a variable local to the 1726function). 1727 1728Using "finish" stops Vim from reading the rest of the file, it's much quicker 1729than using if-endif around the whole file. 1730 1731 1732MAPPING 1733 1734Now let's make the plugin more interesting: We will add a mapping that adds a 1735correction for the word under the cursor. We could just pick a key sequence 1736for this mapping, but the user might already use it for something else. To 1737allow the user to define which keys a mapping in a plugin uses, the <Leader> 1738item can be used: > 1739 1740 22 map <unique> <Leader>a <Plug>TypecorrAdd 1741 1742The "<Plug>TypecorrAdd" thing will do the work, more about that further on. 1743 1744The user can set the "mapleader" variable to the key sequence that he wants 1745this mapping to start with. Thus if the user has done: > 1746 1747 let mapleader = "_" 1748 1749the mapping will define "_a". If the user didn't do this, the default value 1750will be used, which is a backslash. Then a map for "\a" will be defined. 1751 1752Note that <unique> is used, this will cause an error message if the mapping 1753already happened to exist. |:map-<unique>| 1754 1755But what if the user wants to define his own key sequence? We can allow that 1756with this mechanism: > 1757 1758 21 if !hasmapto('<Plug>TypecorrAdd') 1759 22 map <unique> <Leader>a <Plug>TypecorrAdd 1760 23 endif 1761 1762This checks if a mapping to "<Plug>TypecorrAdd" already exists, and only 1763defines the mapping from "<Leader>a" if it doesn't. The user then has a 1764chance of putting this in his vimrc file: > 1765 1766 map ,c <Plug>TypecorrAdd 1767 1768Then the mapped key sequence will be ",c" instead of "_a" or "\a". 1769 1770 1771PIECES 1772 1773If a script gets longer, you often want to break up the work in pieces. You 1774can use functions or mappings for this. But you don't want these functions 1775and mappings to interfere with the ones from other scripts. For example, you 1776could define a function Add(), but another script could try to define the same 1777function. To avoid this, we define the function local to the script by 1778prepending it with "s:". 1779 1780We will define a function that adds a new typing correction: > 1781 1782 30 function s:Add(from, correct) 1783 31 let to = input("type the correction for " . a:from . ": ") 1784 32 exe ":iabbrev " . a:from . " " . to 1785 .. 1786 36 endfunction 1787 1788Now we can call the function s:Add() from within this script. If another 1789script also defines s:Add(), it will be local to that script and can only 1790be called from the script it was defined in. There can also be a global Add() 1791function (without the "s:"), which is again another function. 1792 1793<SID> can be used with mappings. It generates a script ID, which identifies 1794the current script. In our typing correction plugin we use it like this: > 1795 1796 24 noremap <unique> <script> <Plug>TypecorrAdd <SID>Add 1797 .. 1798 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), 1)<CR> 1799 1800Thus when a user types "\a", this sequence is invoked: > 1801 1802 \a -> <Plug>TypecorrAdd -> <SID>Add -> :call <SID>Add() 1803 1804If another script would also map <SID>Add, it would get another script ID and 1805thus define another mapping. 1806 1807Note that instead of s:Add() we use <SID>Add() here. That is because the 1808mapping is typed by the user, thus outside of the script. The <SID> is 1809translated to the script ID, so that Vim knows in which script to look for 1810the Add() function. 1811 1812This is a bit complicated, but it's required for the plugin to work together 1813with other plugins. The basic rule is that you use <SID>Add() in mappings and 1814s:Add() in other places (the script itself, autocommands, user commands). 1815 1816We can also add a menu entry to do the same as the mapping: > 1817 1818 26 noremenu <script> Plugin.Add\ Correction <SID>Add 1819 1820The "Plugin" menu is recommended for adding menu items for plugins. In this 1821case only one item is used. When adding more items, creating a submenu is 1822recommended. For example, "Plugin.CVS" could be used for a plugin that offers 1823CVS operations "Plugin.CVS.checkin", "Plugin.CVS.checkout", etc. 1824 1825Note that in line 28 ":noremap" is used to avoid that any other mappings cause 1826trouble. Someone may have remapped ":call", for example. In line 24 we also 1827use ":noremap", but we do want "<SID>Add" to be remapped. This is why 1828"<script>" is used here. This only allows mappings which are local to the 1829script. |:map-<script>| The same is done in line 26 for ":noremenu". 1830|:menu-<script>| 1831 1832 1833<SID> AND <Plug> *using-<Plug>* 1834 1835Both <SID> and <Plug> are used to avoid that mappings of typed keys interfere 1836with mappings that are only to be used from other mappings. Note the 1837difference between using <SID> and <Plug>: 1838 1839<Plug> is visible outside of the script. It is used for mappings which the 1840 user might want to map a key sequence to. <Plug> is a special code 1841 that a typed key will never produce. 1842 To make it very unlikely that other plugins use the same sequence of 1843 characters, use this structure: <Plug> scriptname mapname 1844 In our example the scriptname is "Typecorr" and the mapname is "Add". 1845 This results in "<Plug>TypecorrAdd". Only the first character of 1846 scriptname and mapname is uppercase, so that we can see where mapname 1847 starts. 1848 1849<SID> is the script ID, a unique identifier for a script. 1850 Internally Vim translates <SID> to "<SNR>123_", where "123" can be any 1851 number. Thus a function "<SID>Add()" will have a name "<SNR>11_Add()" 1852 in one script, and "<SNR>22_Add()" in another. You can see this if 1853 you use the ":function" command to get a list of functions. The 1854 translation of <SID> in mappings is exactly the same, that's how you 1855 can call a script-local function from a mapping. 1856 1857 1858USER COMMAND 1859 1860Now let's add a user command to add a correction: > 1861 1862 38 if !exists(":Correct") 1863 39 command -nargs=1 Correct :call s:Add(<q-args>, 0) 1864 40 endif 1865 1866The user command is defined only if no command with the same name already 1867exists. Otherwise we would get an error here. Overriding the existing user 1868command with ":command!" is not a good idea, this would probably make the user 1869wonder why the command he defined himself doesn't work. |:command| 1870 1871 1872SCRIPT VARIABLES 1873 1874When a variable starts with "s:" it is a script variable. It can only be used 1875inside a script. Outside the script it's not visible. This avoids trouble 1876with using the same variable name in different scripts. The variables will be 1877kept as long as Vim is running. And the same variables are used when sourcing 1878the same script again. |s:var| 1879 1880The fun is that these variables can also be used in functions, autocommands 1881and user commands that are defined in the script. In our example we can add 1882a few lines to count the number of corrections: > 1883 1884 19 let s:count = 4 1885 .. 1886 30 function s:Add(from, correct) 1887 .. 1888 34 let s:count = s:count + 1 1889 35 echo s:count . " corrections now" 1890 36 endfunction 1891 1892First s:count is initialized to 4 in the script itself. When later the 1893s:Add() function is called, it increments s:count. It doesn't matter from 1894where the function was called, since it has been defined in the script, it 1895will use the local variables from this script. 1896 1897 1898THE RESULT 1899 1900Here is the resulting complete example: > 1901 1902 1 " Vim global plugin for correcting typing mistakes 1903 2 " Last Change: 2000 Oct 15 1904 3 " Maintainer: Bram Moolenaar <Bram@vim.org> 1905 4 " License: This file is placed in the public domain. 1906 5 1907 6 if exists("g:loaded_typecorr") 1908 7 finish 1909 8 endif 1910 9 let g:loaded_typecorr = 1 1911 10 1912 11 let s:save_cpo = &cpo 1913 12 set cpo&vim 1914 13 1915 14 iabbrev teh the 1916 15 iabbrev otehr other 1917 16 iabbrev wnat want 1918 17 iabbrev synchronisation 1919 18 \ synchronization 1920 19 let s:count = 4 1921 20 1922 21 if !hasmapto('<Plug>TypecorrAdd') 1923 22 map <unique> <Leader>a <Plug>TypecorrAdd 1924 23 endif 1925 24 noremap <unique> <script> <Plug>TypecorrAdd <SID>Add 1926 25 1927 26 noremenu <script> Plugin.Add\ Correction <SID>Add 1928 27 1929 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), 1)<CR> 1930 29 1931 30 function s:Add(from, correct) 1932 31 let to = input("type the correction for " . a:from . ": ") 1933 32 exe ":iabbrev " . a:from . " " . to 1934 33 if a:correct | exe "normal viws\<C-R>\" \b\e" | endif 1935 34 let s:count = s:count + 1 1936 35 echo s:count . " corrections now" 1937 36 endfunction 1938 37 1939 38 if !exists(":Correct") 1940 39 command -nargs=1 Correct :call s:Add(<q-args>, 0) 1941 40 endif 1942 41 1943 42 let &cpo = s:save_cpo 1944 1945Line 33 wasn't explained yet. It applies the new correction to the word under 1946the cursor. The |:normal| command is used to use the new abbreviation. Note 1947that mappings and abbreviations are expanded here, even though the function 1948was called from a mapping defined with ":noremap". 1949 1950Using "unix" for the 'fileformat' option is recommended. The Vim scripts will 1951then work everywhere. Scripts with 'fileformat' set to "dos" do not work on 1952Unix. Also see |:source_crnl|. To be sure it is set right, do this before 1953writing the file: > 1954 1955 :set fileformat=unix 1956 1957 1958DOCUMENTATION *write-local-help* 1959 1960It's a good idea to also write some documentation for your plugin. Especially 1961when its behavior can be changed by the user. See |add-local-help| for how 1962they are installed. 1963 1964Here is a simple example for a plugin help file, called "typecorr.txt": > 1965 1966 1 *typecorr.txt* Plugin for correcting typing mistakes 1967 2 1968 3 If you make typing mistakes, this plugin will have them corrected 1969 4 automatically. 1970 5 1971 6 There are currently only a few corrections. Add your own if you like. 1972 7 1973 8 Mappings: 1974 9 <Leader>a or <Plug>TypecorrAdd 1975 10 Add a correction for the word under the cursor. 1976 11 1977 12 Commands: 1978 13 :Correct {word} 1979 14 Add a correction for {word}. 1980 15 1981 16 *typecorr-settings* 1982 17 This plugin doesn't have any settings. 1983 1984The first line is actually the only one for which the format matters. It will 1985be extracted from the help file to be put in the "LOCAL ADDITIONS:" section of 1986help.txt |local-additions|. The first "*" must be in the first column of the 1987first line. After adding your help file do ":help" and check that the entries 1988line up nicely. 1989 1990You can add more tags inside ** in your help file. But be careful not to use 1991existing help tags. You would probably use the name of your plugin in most of 1992them, like "typecorr-settings" in the example. 1993 1994Using references to other parts of the help in || is recommended. This makes 1995it easy for the user to find associated help. 1996 1997 1998FILETYPE DETECTION *plugin-filetype* 1999 2000If your filetype is not already detected by Vim, you should create a filetype 2001detection snippet in a separate file. It is usually in the form of an 2002autocommand that sets the filetype when the file name matches a pattern. 2003Example: > 2004 2005 au BufNewFile,BufRead *.foo set filetype=foofoo 2006 2007Write this single-line file as "ftdetect/foofoo.vim" in the first directory 2008that appears in 'runtimepath'. For Unix that would be 2009"~/.vim/ftdetect/foofoo.vim". The convention is to use the name of the 2010filetype for the script name. 2011 2012You can make more complicated checks if you like, for example to inspect the 2013contents of the file to recognize the language. Also see |new-filetype|. 2014 2015 2016SUMMARY *plugin-special* 2017 2018Summary of special things to use in a plugin: 2019 2020s:name Variables local to the script. 2021 2022<SID> Script-ID, used for mappings and functions local to 2023 the script. 2024 2025hasmapto() Function to test if the user already defined a mapping 2026 for functionality the script offers. 2027 2028<Leader> Value of "mapleader", which the user defines as the 2029 keys that plugin mappings start with. 2030 2031:map <unique> Give a warning if a mapping already exists. 2032 2033:noremap <script> Use only mappings local to the script, not global 2034 mappings. 2035 2036exists(":Cmd") Check if a user command already exists. 2037 2038============================================================================== 2039*41.12* Writing a filetype plugin *write-filetype-plugin* *ftplugin* 2040 2041A filetype plugin is like a global plugin, except that it sets options and 2042defines mappings for the current buffer only. See |add-filetype-plugin| for 2043how this type of plugin is used. 2044 2045First read the section on global plugins above |41.11|. All that is said there 2046also applies to filetype plugins. There are a few extras, which are explained 2047here. The essential thing is that a filetype plugin should only have an 2048effect on the current buffer. 2049 2050 2051DISABLING 2052 2053If you are writing a filetype plugin to be used by many people, they need a 2054chance to disable loading it. Put this at the top of the plugin: > 2055 2056 " Only do this when not done yet for this buffer 2057 if exists("b:did_ftplugin") 2058 finish 2059 endif 2060 let b:did_ftplugin = 1 2061 2062This also needs to be used to avoid that the same plugin is executed twice for 2063the same buffer (happens when using an ":edit" command without arguments). 2064 2065Now users can disable loading the default plugin completely by making a 2066filetype plugin with only this line: > 2067 2068 let b:did_ftplugin = 1 2069 2070This does require that the filetype plugin directory comes before $VIMRUNTIME 2071in 'runtimepath'! 2072 2073If you do want to use the default plugin, but overrule one of the settings, 2074you can write the different setting in a script: > 2075 2076 setlocal textwidth=70 2077 2078Now write this in the "after" directory, so that it gets sourced after the 2079distributed "vim.vim" ftplugin |after-directory|. For Unix this would be 2080"~/.vim/after/ftplugin/vim.vim". Note that the default plugin will have set 2081"b:did_ftplugin", but it is ignored here. 2082 2083 2084OPTIONS 2085 2086To make sure the filetype plugin only affects the current buffer use the > 2087 2088 :setlocal 2089 2090command to set options. And only set options which are local to a buffer (see 2091the help for the option to check that). When using |:setlocal| for global 2092options or options local to a window, the value will change for many buffers, 2093and that is not what a filetype plugin should do. 2094 2095When an option has a value that is a list of flags or items, consider using 2096"+=" and "-=" to keep the existing value. Be aware that the user may have 2097changed an option value already. First resetting to the default value and 2098then changing it often a good idea. Example: > 2099 2100 :setlocal formatoptions& formatoptions+=ro 2101 2102 2103MAPPINGS 2104 2105To make sure mappings will only work in the current buffer use the > 2106 2107 :map <buffer> 2108 2109command. This needs to be combined with the two-step mapping explained above. 2110An example of how to define functionality in a filetype plugin: > 2111 2112 if !hasmapto('<Plug>JavaImport') 2113 map <buffer> <unique> <LocalLeader>i <Plug>JavaImport 2114 endif 2115 noremap <buffer> <unique> <Plug>JavaImport oimport ""<Left><Esc> 2116 2117|hasmapto()| is used to check if the user has already defined a map to 2118<Plug>JavaImport. If not, then the filetype plugin defines the default 2119mapping. This starts with |<LocalLeader>|, which allows the user to select 2120the key(s) he wants filetype plugin mappings to start with. The default is a 2121backslash. 2122"<unique>" is used to give an error message if the mapping already exists or 2123overlaps with an existing mapping. 2124|:noremap| is used to avoid that any other mappings that the user has defined 2125interferes. You might want to use ":noremap <script>" to allow remapping 2126mappings defined in this script that start with <SID>. 2127 2128The user must have a chance to disable the mappings in a filetype plugin, 2129without disabling everything. Here is an example of how this is done for a 2130plugin for the mail filetype: > 2131 2132 " Add mappings, unless the user didn't want this. 2133 if !exists("no_plugin_maps") && !exists("no_mail_maps") 2134 " Quote text by inserting "> " 2135 if !hasmapto('<Plug>MailQuote') 2136 vmap <buffer> <LocalLeader>q <Plug>MailQuote 2137 nmap <buffer> <LocalLeader>q <Plug>MailQuote 2138 endif 2139 vnoremap <buffer> <Plug>MailQuote :s/^/> /<CR> 2140 nnoremap <buffer> <Plug>MailQuote :.,$s/^/> /<CR> 2141 endif 2142 2143Two global variables are used: 2144no_plugin_maps disables mappings for all filetype plugins 2145no_mail_maps disables mappings for a specific filetype 2146 2147 2148USER COMMANDS 2149 2150To add a user command for a specific file type, so that it can only be used in 2151one buffer, use the "-buffer" argument to |:command|. Example: > 2152 2153 :command -buffer Make make %:r.s 2154 2155 2156VARIABLES 2157 2158A filetype plugin will be sourced for each buffer of the type it's for. Local 2159script variables |s:var| will be shared between all invocations. Use local 2160buffer variables |b:var| if you want a variable specifically for one buffer. 2161 2162 2163FUNCTIONS 2164 2165When defining a function, this only needs to be done once. But the filetype 2166plugin will be sourced every time a file with this filetype will be opened. 2167This construct makes sure the function is only defined once: > 2168 2169 :if !exists("*s:Func") 2170 : function s:Func(arg) 2171 : ... 2172 : endfunction 2173 :endif 2174< 2175 2176UNDO *undo_ftplugin* 2177 2178When the user does ":setfiletype xyz" the effect of the previous filetype 2179should be undone. Set the b:undo_ftplugin variable to the commands that will 2180undo the settings in your filetype plugin. Example: > 2181 2182 let b:undo_ftplugin = "setlocal fo< com< tw< commentstring<" 2183 \ . "| unlet b:match_ignorecase b:match_words b:match_skip" 2184 2185Using ":setlocal" with "<" after the option name resets the option to its 2186global value. That is mostly the best way to reset the option value. 2187 2188This does require removing the "C" flag from 'cpoptions' to allow line 2189continuation, as mentioned above |use-cpo-save|. 2190 2191 2192FILE NAME 2193 2194The filetype must be included in the file name |ftplugin-name|. Use one of 2195these three forms: 2196 2197 .../ftplugin/stuff.vim 2198 .../ftplugin/stuff_foo.vim 2199 .../ftplugin/stuff/bar.vim 2200 2201"stuff" is the filetype, "foo" and "bar" are arbitrary names. 2202 2203 2204SUMMARY *ftplugin-special* 2205 2206Summary of special things to use in a filetype plugin: 2207 2208<LocalLeader> Value of "maplocalleader", which the user defines as 2209 the keys that filetype plugin mappings start with. 2210 2211:map <buffer> Define a mapping local to the buffer. 2212 2213:noremap <script> Only remap mappings defined in this script that start 2214 with <SID>. 2215 2216:setlocal Set an option for the current buffer only. 2217 2218:command -buffer Define a user command local to the buffer. 2219 2220exists("*s:Func") Check if a function was already defined. 2221 2222Also see |plugin-special|, the special things used for all plugins. 2223 2224============================================================================== 2225*41.13* Writing a compiler plugin *write-compiler-plugin* 2226 2227A compiler plugin sets options for use with a specific compiler. The user can 2228load it with the |:compiler| command. The main use is to set the 2229'errorformat' and 'makeprg' options. 2230 2231Easiest is to have a look at examples. This command will edit all the default 2232compiler plugins: > 2233 2234 :next $VIMRUNTIME/compiler/*.vim 2235 2236Use |:next| to go to the next plugin file. 2237 2238There are two special items about these files. First is a mechanism to allow 2239a user to overrule or add to the default file. The default files start with: > 2240 2241 :if exists("current_compiler") 2242 : finish 2243 :endif 2244 :let current_compiler = "mine" 2245 2246When you write a compiler file and put it in your personal runtime directory 2247(e.g., ~/.vim/compiler for Unix), you set the "current_compiler" variable to 2248make the default file skip the settings. 2249 *:CompilerSet* 2250The second mechanism is to use ":set" for ":compiler!" and ":setlocal" for 2251":compiler". Vim defines the ":CompilerSet" user command for this. However, 2252older Vim versions don't, thus your plugin should define it then. This is an 2253example: > 2254 2255 if exists(":CompilerSet") != 2 2256 command -nargs=* CompilerSet setlocal <args> 2257 endif 2258 CompilerSet errorformat& " use the default 'errorformat' 2259 CompilerSet makeprg=nmake 2260 2261When you write a compiler plugin for the Vim distribution or for a system-wide 2262runtime directory, use the mechanism mentioned above. When 2263"current_compiler" was already set by a user plugin nothing will be done. 2264 2265When you write a compiler plugin to overrule settings from a default plugin, 2266don't check "current_compiler". This plugin is supposed to be loaded 2267last, thus it should be in a directory at the end of 'runtimepath'. For Unix 2268that could be ~/.vim/after/compiler. 2269 2270============================================================================== 2271*41.14* Writing a plugin that loads quickly *write-plugin-quickload* 2272 2273A plugin may grow and become quite long. The startup delay may become 2274noticeable, while you hardly ever use the plugin. Then it's time for a 2275quickload plugin. 2276 2277The basic idea is that the plugin is loaded twice. The first time user 2278commands and mappings are defined that offer the functionality. The second 2279time the functions that implement the functionality are defined. 2280 2281It may sound surprising that quickload means loading a script twice. What we 2282mean is that it loads quickly the first time, postponing the bulk of the 2283script to the second time, which only happens when you actually use it. When 2284you always use the functionality it actually gets slower! 2285 2286Note that since Vim 7 there is an alternative: use the |autoload| 2287functionality |41.15|. 2288 2289The following example shows how it's done: > 2290 2291 " Vim global plugin for demonstrating quick loading 2292 " Last Change: 2005 Feb 25 2293 " Maintainer: Bram Moolenaar <Bram@vim.org> 2294 " License: This file is placed in the public domain. 2295 2296 if !exists("s:did_load") 2297 command -nargs=* BNRead call BufNetRead(<f-args>) 2298 map <F19> :call BufNetWrite('something')<CR> 2299 2300 let s:did_load = 1 2301 exe 'au FuncUndefined BufNet* source ' . expand('<sfile>') 2302 finish 2303 endif 2304 2305 function BufNetRead(...) 2306 echo 'BufNetRead(' . string(a:000) . ')' 2307 " read functionality here 2308 endfunction 2309 2310 function BufNetWrite(...) 2311 echo 'BufNetWrite(' . string(a:000) . ')' 2312 " write functionality here 2313 endfunction 2314 2315When the script is first loaded "s:did_load" is not set. The commands between 2316the "if" and "endif" will be executed. This ends in a |:finish| command, thus 2317the rest of the script is not executed. 2318 2319The second time the script is loaded "s:did_load" exists and the commands 2320after the "endif" are executed. This defines the (possible long) 2321BufNetRead() and BufNetWrite() functions. 2322 2323If you drop this script in your plugin directory Vim will execute it on 2324startup. This is the sequence of events that happens: 2325 23261. The "BNRead" command is defined and the <F19> key is mapped when the script 2327 is sourced at startup. A |FuncUndefined| autocommand is defined. The 2328 ":finish" command causes the script to terminate early. 2329 23302. The user types the BNRead command or presses the <F19> key. The 2331 BufNetRead() or BufNetWrite() function will be called. 2332 23333. Vim can't find the function and triggers the |FuncUndefined| autocommand 2334 event. Since the pattern "BufNet*" matches the invoked function, the 2335 command "source fname" will be executed. "fname" will be equal to the name 2336 of the script, no matter where it is located, because it comes from 2337 expanding "<sfile>" (see |expand()|). 2338 23394. The script is sourced again, the "s:did_load" variable exists and the 2340 functions are defined. 2341 2342Notice that the functions that are loaded afterwards match the pattern in the 2343|FuncUndefined| autocommand. You must make sure that no other plugin defines 2344functions that match this pattern. 2345 2346============================================================================== 2347*41.15* Writing library scripts *write-library-script* 2348 2349Some functionality will be required in several places. When this becomes more 2350than a few lines you will want to put it in one script and use it from many 2351scripts. We will call that one script a library script. 2352 2353Manually loading a library script is possible, so long as you avoid loading it 2354when it's already done. You can do this with the |exists()| function. 2355Example: > 2356 2357 if !exists('*MyLibFunction') 2358 runtime library/mylibscript.vim 2359 endif 2360 call MyLibFunction(arg) 2361 2362Here you need to know that MyLibFunction() is defined in a script 2363"library/mylibscript.vim" in one of the directories in 'runtimepath'. 2364 2365To make this a bit simpler Vim offers the autoload mechanism. Then the 2366example looks like this: > 2367 2368 call mylib#myfunction(arg) 2369 2370That's a lot simpler, isn't it? Vim will recognize the function name and when 2371it's not defined search for the script "autoload/mylib.vim" in 'runtimepath'. 2372That script must define the "mylib#myfunction()" function. 2373 2374You can put many other functions in the mylib.vim script, you are free to 2375organize your functions in library scripts. But you must use function names 2376where the part before the '#' matches the script name. Otherwise Vim would 2377not know what script to load. 2378 2379If you get really enthusiastic and write lots of library scripts, you may 2380want to use subdirectories. Example: > 2381 2382 call netlib#ftp#read('somefile') 2383 2384For Unix the library script used for this could be: 2385 2386 ~/.vim/autoload/netlib/ftp.vim 2387 2388Where the function is defined like this: > 2389 2390 function netlib#ftp#read(fname) 2391 " Read the file fname through ftp 2392 endfunction 2393 2394Notice that the name the function is defined with is exactly the same as the 2395name used for calling the function. And the part before the last '#' 2396exactly matches the subdirectory and script name. 2397 2398You can use the same mechanism for variables: > 2399 2400 let weekdays = dutch#weekdays 2401 2402This will load the script "autoload/dutch.vim", which should contain something 2403like: > 2404 2405 let dutch#weekdays = ['zondag', 'maandag', 'dinsdag', 'woensdag', 2406 \ 'donderdag', 'vrijdag', 'zaterdag'] 2407 2408Further reading: |autoload|. 2409 2410============================================================================== 2411*41.16* Distributing Vim scripts *distribute-script* 2412 2413Vim users will look for scripts on the Vim website: http://www.vim.org. 2414If you made something that is useful for others, share it! 2415 2416Vim scripts can be used on any system. There might not be a tar or gzip 2417command. If you want to pack files together and/or compress them the "zip" 2418utility is recommended. 2419 2420For utmost portability use Vim itself to pack scripts together. This can be 2421done with the Vimball utility. See |vimball|. 2422 2423It's good if you add a line to allow automatic updating. See |glvs-plugins|. 2424 2425============================================================================== 2426 2427Next chapter: |usr_42.txt| Add new menus 2428 2429Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: 2430