1 *usr_41.txt* For Vim version 7.3. Last change: 2010 Jul 20
3 VIM USER MANUAL - by Bram Moolenaar
8 The Vim script language is used for the startup vimrc file, syntax files, and
9 many other things. This chapter explains the items that can be used in a Vim
10 script. There are a lot of them, thus this is a long chapter.
16 |41.5| Executing an expression
17 |41.6| Using functions
18 |41.7| Defining a function
19 |41.8| Lists and Dictionaries
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
29 Next chapter: |usr_42.txt| Add new menus
30 Previous chapter: |usr_40.txt| Make new commands
31 Table of contents: |usr_toc.txt|
33 ==============================================================================
34 *41.1* Introduction *vim-script-intro* *script*
36 Your first experience with Vim scripts is the vimrc file. Vim reads it when
37 it starts up and executes the commands. You can set options to values you
38 prefer. 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
41 specific file type. A complicated macro can be defined by a separate Vim
42 script file. You can think of other uses yourself.
44 Let's start with a simple example: >
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.
58 You can try out the examples by yanking the lines from the text here
59 and executing them with :@"
61 The output of the example code is:
68 In the first line the ":let" command assigns a value to a variable. The
71 :let {variable} = {expression}
73 In this case the variable name is "i" and the expression is a simple value,
75 The ":while" command starts a loop. The generic form is: >
81 The statements until the matching ":endwhile" are executed for as long as the
82 condition is true. The condition used here is the expression "i < 5". This
83 is true when the variable i is smaller than five.
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).
88 The ":echo" command prints its arguments. In this case the string "count is"
89 and the value of the variable i. Since i is one, this will print:
93 Then 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
97 The example was given to explain the commands, but would you really want to
98 make such a loop it can be written much more compact: >
100 :for i in range(1, 4)
104 We won't explain how |:for| and |range()| work until later. Follow the links
105 if you are impatient.
108 THREE KINDS OF NUMBERS
110 Numbers can be decimal, hexadecimal or octal. A hexadecimal number starts
111 with "0x" or "0X". For example "0x1f" is decimal 31. An octal number starts
112 with a zero. "017" is decimal 15. Careful: don't put a zero before a decimal
113 number, it will be interpreted as an octal number!
114 The ":echo" command always prints decimal numbers. Example: >
119 A number is made negative with a minus sign. This also works for hexadecimal
120 and octal numbers. A minus sign is also used for subtraction. Compare this
121 with the previous example: >
126 White space in an expression is ignored. However, it's recommended to use it
127 for separating items, to make the expression easier to read. For example, to
128 avoid the confusion with a negative number above, put a space between the
129 minus sign and the following number: >
133 ==============================================================================
136 A variable name consists of ASCII letters, digits and the underscore. It
137 cannot start with a digit. Valid variable names are:
141 very_long_variable_name_with_underscores
145 Invalid names are "foo+bar" and "6var".
146 These variables are global. To see a list of currently defined variables
151 You can use global variables everywhere. This also means that when the
152 variable "count" is used in one script file, it might also be used in another
153 file. This leads to confusion at least, and real problems at worst. To avoid
154 this, you can use a variable local to a script file by prepending "s:". For
155 example, one script contains this code: >
163 Since "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
166 about script-local variables here: |script-variable|.
168 There are more kinds of variables, see |internal-variables|. The most often
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
179 Variables take up memory and show up in the output of the ":let" command. To
180 delete a variable use the ":unlet" command. Example: >
184 This deletes the script-local variable "s:count" to free up the memory it
185 uses. If you are not sure if the variable exists, and don't want an error
186 message when it doesn't, append !: >
190 When a script finishes, the local variables used there will not be
191 automatically freed. The next time the script executes, it can still use the
192 old value. Example: >
194 :if !exists("s:call_count")
195 : let s:call_count = 0
197 :let s:call_count = s:call_count + 1
198 :echo "called" s:call_count "times"
200 The "exists()" function checks if a variable has already been defined. Its
201 argument is the name of the variable you want to check. Not the variable
202 itself! If you would do this: >
204 :if !exists(s:call_count)
206 Then the value of s:call_count will be used as the name of the variable that
207 exists() checks. That's not what you want.
208 The exclamation mark ! negates a value. When the value was true, it
209 becomes false. When it was false, it becomes true. You can read it as "not".
210 Thus "if !exists()" can be read as "if not exists()".
211 What Vim calls true is anything that is not zero. Zero is false.
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: >
217 < The "true" will be interpreted as a zero, thus as false!
220 STRING VARIABLES AND CONSTANTS
222 So far only numbers were used for the variable value. Strings can be used as
223 well. Numbers and strings are the basic types of variables that Vim supports.
224 The type is dynamic, it is set each time when assigning a value to the
225 variable with ":let". More about types in |41.8|.
226 To assign a string value to a variable, you need to use a string constant.
227 There are two types of these. First the string in double quotes: >
233 If you want to include a double quote inside the string, put a backslash in
236 :let name = "\"peter\""
240 To avoid the need for a backslash, you can use a string in single quotes: >
242 :let name = '"peter"'
246 Inside a single-quote string all the characters are as they are. Only the
247 single quote itself is special: you need to use two to get one. A backslash
248 is taken literally, thus you can't use it to change the meaning of the
250 In double-quote strings it is possible to use special characters. Here are
263 The last two are just examples. The "\<name>" form can be used to include
264 the special key "name".
265 See |expr-quote| for the full list of special items in a string.
267 ==============================================================================
270 Vim has a rich, yet simple way to handle expressions. You can read the
271 definition here: |expression-syntax|. Here we will show the most common
273 The numbers, strings and variables mentioned above are expressions by
274 themselves. Thus everywhere an expression is expected, you can use a number,
275 string or variable. Other basic items in an expression are:
277 $NAME environment variable
283 :echo "The value of 'tabstop' is" &ts
284 :echo "Your home directory is" $HOME
287 The &name form can be used to save an option value, set it to a new value,
288 do something and restore the old value. Example: >
295 This makes sure the "The Start" pattern is used with the 'ignorecase' option
296 off. Still, it keeps the value that the user had set. (Another way to do
297 this would be to add "\C" to the pattern, see |/\C|.)
302 It becomes more interesting if we combine these basic items. Let's start with
303 mathematics on numbers:
311 The usual precedence is used. Example: >
316 Grouping is done with braces. No surprises here. Example: >
321 Strings can be concatenated with ".". Example: >
326 When the ":echo" command gets multiple arguments, it separates them with a
327 space. In the example the argument is a single expression, thus no space is
330 Borrowed from the C language is the conditional expression:
334 If "a" evaluates to true "b" is used, otherwise "c" is used. Example: >
337 :echo i > 5 ? "i is big" : "i is small"
340 The three parts of the constructs are always evaluated first, thus you could
345 ==============================================================================
348 The ":if" commands executes the following statements, until the matching
349 ":endif", only when a condition is met. The generic form is:
355 Only when the expression {condition} evaluates to true (non-zero) will the
356 {statements} be executed. These must still be valid commands. If they
357 contain garbage, Vim won't be able to find the ":endif".
358 You can also use ":else". The generic form for this is:
366 The second {statements} is only executed if the first one isn't.
367 Finally, there is ":elseif":
375 This works just like using ":else" and then "if", but without the need for an
377 A useful example for your vimrc file is checking the 'term' option and
378 doing something depending upon its value: >
381 : " Do stuff for xterm
382 :elseif &term == "vt100"
383 : " Do stuff for a vt100 terminal
385 : " Do something for other terminals
391 We already used some of them in the examples. These are the most often used
397 a >= b greater than or equal to
399 a <= b less than or equal to
401 The result is one if the condition is met and zero otherwise. An example: >
404 : echo "congratulations"
406 : echo "you are using an old version, upgrade!"
409 Here "v:version" is a variable defined by Vim, which has the value of the Vim
410 version. 600 is for version 6.0. Version 6.1 has the value 601. This is
411 very useful to write a script that works with multiple versions of Vim.
414 The logic operators work both for numbers and strings. When comparing two
415 strings, the mathematical difference is used. This compares byte values,
416 which may not be right for some languages.
417 When comparing a string with a number, the string is first converted to a
418 number. This is a bit tricky, because when a string doesn't look like a
419 number, the number zero is used. Example: >
425 This will echo "yes", because "one" doesn't look like a number, thus it is
426 converted to the number zero.
428 For strings there are two more items:
431 a !~ b does not match with
433 The left item "a" is used as a string. The right item "b" is used as a
434 pattern, like what's used for searching. Example: >
437 : echo "str contains a space"
440 : echo "str does not end in a full stop"
443 Notice the use of a single-quote string for the pattern. This is useful,
444 because backslashes would need to be doubled in a double-quote string and
445 patterns tend to contain many backslashes.
447 The 'ignorecase' option is used when comparing strings. When you don't want
448 that, append "#" to match case and "?" to ignore case. Thus "==?" compares
449 two strings to be equal while ignoring case. And "!~#" checks if a pattern
450 doesn't match, also checking the case of letters. For the full table see
456 The ":while" command was already mentioned. Two more statements can be used
457 in between the ":while" and the ":endwhile":
459 :continue Jump back to the start of the while loop; the
461 :break Jump forward to the ":endwhile"; the loop is
467 : call do_something()
477 The ":sleep" command makes Vim take a nap. The "50m" specifies fifty
478 milliseconds. Another example is ":sleep 4", which sleeps for four seconds.
480 Even more looping can be done with the ":for" command, see below in |41.8|.
482 ==============================================================================
483 *41.5* Executing an expression
485 So 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
487 very powerful way to build commands and execute them.
488 An example is to jump to a tag, which is contained in a variable: >
490 :execute "tag " . tag_name
492 The "." 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
494 will be executed is: >
498 The ":execute" command can only execute colon commands. The ":normal" command
499 executes Normal mode commands. However, its argument is not an expression but
500 the literal command characters. Example: >
504 This jumps to the first line and formats all lines with the "=" operator.
505 To make ":normal" work with an expression, combine ":execute" with it.
508 :execute "normal " . normal_commands
510 The variable "normal_commands" must contain the Normal mode commands.
511 Make sure that the argument for ":normal" is a complete command. Otherwise
512 Vim will run into the end of the argument and abort the command. For example,
513 if you start Insert mode, you must leave Insert mode as well. This works: >
515 :execute "normal Inew text \<Esc>"
517 This inserts "new text " in the current line. Notice the use of the special
518 key "\<Esc>". This avoids having to enter a real <Esc> character in your
521 If you don't want to execute a string but evaluate it to get its expression
522 value, you can use the eval() function: >
524 :let optname = "path"
525 :let optval = eval('&' . optname)
527 A "&" 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
532 ==============================================================================
533 *41.6* Using functions
535 Vim defines many functions and provides a large amount of functionality that
536 way. A few examples will be given in this section. You can find the whole
537 list here: |functions|.
539 A function is called with the ":call" command. The parameters are passed in
540 between braces, separated by commas. Example: >
542 :call search("Date: ", "W")
544 This calls the search() function, with arguments "Date: " and "W". The
545 search() function uses its first argument as a search pattern and the second
546 one as flags. The "W" flag means the search doesn't wrap around the end of
549 A function can be called in an expression. Example: >
551 :let line = getline(".")
552 :let repl = substitute(line, '\a', "*", "g")
553 :call setline(".", repl)
555 The getline() function obtains a line from the current buffer. Its argument
556 is a specification of the line number. In this case "." is used, which means
557 the line where the cursor is.
558 The substitute() function does something similar to the ":substitute"
559 command. The first argument is the string on which to perform the
560 substitution. The second argument is the pattern, the third the replacement
561 string. Finally, the last arguments are the flags.
562 The setline() function sets the line, specified by the first argument, to a
563 new string, the second argument. In this example the line under the cursor is
564 replaced with the result of the substitute(). Thus the effect of the three
565 statements is equal to: >
569 Using the functions becomes more interesting when you do more work before and
570 after the substitute() call.
573 FUNCTIONS *function-list*
575 There are many functions. We will mention them here, grouped by what they are
576 used for. You can find an alphabetical list here: |functions|. Use CTRL-] on
577 the function name to jump to detailed help on it.
579 String 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
608 List 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
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
633 Dictionary 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
652 Floating point computation: *float-functions*
653 float2nr() convert Float to Number
654 abs() absolute value (also works for Number)
658 trunc() remove value after decimal point
659 log10() logarithm to base 10
660 pow() value of x to the exponent y
666 Variables: *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
680 Cursor 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
693 Working 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
708 *system-functions* *file-functions*
709 System 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
736 Date 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
743 *buffer-functions* *window-functions* *arg-functions*
744 Buffers, 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
761 Command 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
767 Quickfix 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
773 Insert 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
779 Folding: *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
786 Syntax 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
801 setmatches() restore a list of matches saved by
804 Spelling: *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
809 History: *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
815 Interactive: *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
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
834 Vim 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
844 Window 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
851 Various: *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
865 libcall() call a function in an external library
866 libcallnr() idem, returning a number
868 getreg() get contents of a register
869 getregtype() get type of a register
870 setreg() set contents and type of a register
872 taglist() get list of matching tags
873 tagfiles() get a list of tags files
875 mzeval() evaluate |MzScheme| expression
877 ==============================================================================
878 *41.7* Defining a function
880 Vim enables you to define your own functions. The basic function declaration
883 :function {name}({var1}, {var2}, ...)
888 Function names must begin with a capital letter.
890 Let's define a short function to return the smaller of two numbers. It starts
893 :function Min(num1, num2)
895 This tells Vim that the function is named "Min" and it takes two arguments:
897 The first thing you need to do is to check to see which number is smaller:
901 The special prefix "a:" tells Vim that the variable is a function argument.
902 Let's assign the variable "smaller" the value of the smallest number: >
905 : let smaller = a:num1
907 : let smaller = a:num2
910 The variable "smaller" is a local variable. Variables used inside a function
911 are local unless prefixed by something like "g:", "a:", or "s:".
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
919 You now use the ":return" statement to return the smallest number to the user.
920 Finally, you end the function: >
925 The complete function definition is as follows: >
927 :function Min(num1, num2)
929 : let smaller = a:num1
931 : let smaller = a:num2
936 For people who like short functions, this does the same thing: >
938 :function Min(num1, num2)
945 A user defined function is called in exactly the same way as a built-in
946 function. Only the name is different. The Min function can be used like
951 Only now will the function be executed and the lines be interpreted by Vim.
952 If there are mistakes, like using an undefined variable or function, you will
953 now get an error message. When defining the function these errors are not
956 When a function reaches ":endfunction" or ":return" is used without an
957 argument, the function returns zero.
959 To redefine a function that already exists, use the ! for the ":function"
962 :function! Min(num1, num2, num3)
967 The ":call" command can be given a line range. This can have one of two
968 meanings. When a function has been defined with the "range" keyword, it will
969 take care of the line range itself.
970 The function will be passed the variables "a:firstline" and "a:lastline".
971 These will have the line numbers from the range the function was called with.
974 :function Count_words() range
975 : let lnum = a:firstline
977 : while lnum <= a:lastline
978 : let n = n + len(split(getline(lnum)))
979 : let lnum = lnum + 1
981 : echo "found " . n . " words"
984 You can call this function with: >
986 :10,30call Count_words()
988 It 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
991 range, with the cursor in that line. Example: >
994 : echo "line " . line(".") . " contains: " . getline(".")
997 If you call this function with: >
1001 The function will be called six times.
1004 VARIABLE NUMBER OF ARGUMENTS
1006 Vim enables you to define functions that have a variable number of arguments.
1007 The following command, for instance, defines a function that must have 1
1008 argument (start) and can have up to 20 additional arguments: >
1010 :function Show(start, ...)
1012 The variable "a:1" contains the first optional argument, "a:2" the second, and
1013 so on. The variable "a:0" contains the number of extra arguments.
1016 :function Show(start, ...)
1018 : echo "Show is " . a:start
1021 : while index <= a:0
1022 : echo " Arg " . index . " is " . a:{index}
1023 : let index = index + 1
1028 This uses the ":echohl" command to specify the highlighting used for the
1029 following ":echo" command. ":echohl None" stops it again. The ":echon"
1030 command works like ":echo", but doesn't output a line break.
1032 You can also use the a:000 variable, it is a List of all the "..." arguments.
1038 The ":function" command lists the names and arguments of all user-defined
1042 < function Show(start, ...) ~
1043 function GetVimIndent() ~
1044 function SetSyn(name) ~
1046 To see what a function does, use its name as an argument for ":function": >
1049 < 1 if &syntax == '' ~
1050 2 let &syntax = a:name ~
1057 The line number is useful for when you get an error message or when debugging.
1058 See |debug-scripts| about debugging mode.
1059 You can also set the 'verbose' option to 12 or higher to see all function
1060 calls. Set it to 15 or higher to see every executed line.
1065 To delete the Show() function: >
1069 You get an error when the function doesn't exist.
1074 Sometimes it can be useful to have a variable point to one function or
1075 another. You can do it with the function() function. It turns the name of a
1076 function into a reference: >
1078 :let result = 0 " or 1
1087 : let Afunc = function('Right')
1089 : let Afunc = function('Wrong')
1091 :echo call(Afunc, [])
1094 Note that the name of a variable that holds a function reference must start
1095 with a capital. Otherwise it could be confused with the name of a builtin
1097 The way to invoke a function that a variable refers to is with the call()
1098 function. Its first argument is the function reference, the second argument
1099 is a List with arguments.
1101 Function references are most useful in combination with a Dictionary, as is
1102 explained in the next section.
1104 ==============================================================================
1105 *41.8* Lists and Dictionaries
1107 So far we have used the basic types String and Number. Vim also supports two
1108 composite types: List and Dictionary.
1110 A List is an ordered sequence of things. The things can be any kind of value,
1111 thus you can make a List of numbers, a List of Lists and even a List of mixed
1112 items. To create a List with three strings: >
1114 :let alist = ['aap', 'mies', 'noot']
1116 The List items are enclosed in square brackets and separated by commas. To
1117 create an empty List: >
1121 You can add items to a List with the add() function: >
1124 :call add(alist, 'foo')
1125 :call add(alist, 'bar')
1129 List concatenation is done with +: >
1131 :echo alist + ['foo', 'bar']
1132 < ['foo', 'bar', 'foo', 'bar'] ~
1134 Or, if you want to extend a List directly: >
1136 :let alist = ['one']
1137 :call extend(alist, ['two', 'three'])
1139 < ['one', 'two', 'three'] ~
1141 Notice that using add() will have a different effect: >
1143 :let alist = ['one']
1144 :call add(alist, ['two', 'three'])
1146 < ['one', ['two', 'three']] ~
1148 The second argument of add() is added as a single item.
1153 One of the nice things you can do with a List is iterate over it: >
1155 :let alist = ['one', 'two', 'three']
1163 This will loop over each element in List "alist", assigning the value to
1164 variable "n". The generic form of a for loop is: >
1166 :for {varname} in {listexpression}
1170 To loop a certain number of times you need a List of a specific length. The
1171 range() function creates one for you: >
1180 Notice that the first item of the List that range() produces is zero, thus the
1181 last item is one less than the length of the list.
1182 You can also specify the maximum value, the stride and even go backwards: >
1184 :for a in range(8, 4, -2)
1191 A more useful example, looping over lines in the buffer: >
1193 :for line in getline(1, 20)
1194 : if line =~ "Date: "
1195 : echo matchstr(line, 'Date: \zs.*')
1199 This looks into lines 1 to 20 (inclusive) and echoes any date found in there.
1204 A Dictionary stores key-value pairs. You can quickly lookup a value if you
1205 know the key. A Dictionary is created with curly braces: >
1207 :let uk2nl = {'one': 'een', 'two': 'twee', 'three': 'drie'}
1209 Now you can lookup words by putting the key in square brackets: >
1214 The generic form for defining a Dictionary is: >
1216 {<key> : <value>, ...}
1218 An empty Dictionary is one without any keys: >
1222 The possibilities with Dictionaries are numerous. There are various functions
1223 for them as well. For example, you can obtain a list of the keys and loop
1226 :for key in keys(uk2nl)
1233 You will notice the keys are not ordered. You can sort the list to get a
1236 :for key in sort(keys(uk2nl))
1243 But you can never get back the order in which items are defined. For that you
1244 need to use a List, it stores items in an ordered sequence.
1247 DICTIONARY FUNCTIONS
1249 The items in a Dictionary can normally be obtained with an index in square
1255 A method that does the same, but without so many punctuation characters: >
1260 This only works for a key that is made of ASCII letters, digits and the
1261 underscore. You can also assign a new value this way: >
1263 :let uk2nl.four = 'vier'
1265 < {'three': 'drie', 'four': 'vier', 'one': 'een', 'two': 'twee'} ~
1267 And now for something special: you can directly define a function and store a
1268 reference to it in the dictionary: >
1270 :function uk2nl.translate(line) dict
1271 : return join(map(split(a:line), 'get(self, v:val, "???")'))
1274 Let's first try it out: >
1276 :echo uk2nl.translate('three two five one')
1277 < drie twee ??? een ~
1279 The first special thing you notice is the "dict" at the end of the ":function"
1280 line. This marks the function as being used from a Dictionary. The "self"
1281 local variable will then refer to that Dictionary.
1282 Now let's break up the complicated return command: >
1286 The split() function takes a string, chops it into white separated words
1287 and returns a list with these words. Thus in the example it returns: >
1289 :echo split('three two five one')
1290 < ['three', 'two', 'five', 'one'] ~
1292 This list is the first argument to the map() function. This will go through
1293 the list, evaluating its second argument with "v:val" set to the value of each
1294 item. This is a shortcut to using a for loop. This command: >
1296 :let alist = map(split(a:line), 'get(self, v:val, "???")')
1300 :let alist = split(a:line)
1301 :for idx in range(len(alist))
1302 : let alist[idx] = get(self, alist[idx], "???")
1305 The get() function checks if a key is present in a Dictionary. If it is, then
1306 the value is retrieved. If it isn't, then the default value is returned, in
1307 the example it's '???'. This is a convenient way to handle situations where a
1308 key may not be present and you don't want an error message.
1310 The join() function does the opposite of split(): it joins together a list of
1311 words, putting a space in between.
1312 This combination of split(), map() and join() is a nice way to filter a line
1313 of words in a very compact way.
1316 OBJECT ORIENTED PROGRAMMING
1318 Now that you can put both values and functions in a Dictionary, you can
1319 actually use a Dictionary like an object.
1320 Above we used a Dictionary for translating Dutch to English. We might want
1321 to do the same for other languages. Let's first make an object (aka
1322 Dictionary) that has the translate function, but no words to translate: >
1325 :function transdict.translate(line) dict
1326 : return join(map(split(a:line), 'get(self.words, v:val, "???")'))
1329 It's slightly different from the function above, using 'self.words' to lookup
1330 word translations. But we don't have a self.words. Thus you could call this
1333 Now we can instantiate a Dutch translation object: >
1335 :let uk2nl = copy(transdict)
1336 :let uk2nl.words = {'one': 'een', 'two': 'twee', 'three': 'drie'}
1337 :echo uk2nl.translate('three one')
1340 And a German translator: >
1342 :let uk2de = copy(transdict)
1343 :let uk2de.words = {'one': 'ein', 'two': 'zwei', 'three': 'drei'}
1344 :echo uk2de.translate('three one')
1347 You see that the copy() function is used to make a copy of the "transdict"
1348 Dictionary and then the copy is changed to add the words. The original
1349 remains the same, of course.
1351 Now you can go one step further, and use your preferred translator: >
1358 :echo trans.translate('one two three')
1361 Here "trans" refers to one of the two objects (Dictionaries). No copy is
1362 made. More about List and Dictionary identity can be found at |list-identity|
1363 and |dict-identity|.
1365 Now you might use a language that isn't supported. You can overrule the
1366 translate() function to do nothing: >
1368 :let uk2uk = copy(transdict)
1369 :function! uk2uk.translate(line)
1372 :echo uk2uk.translate('three one wladiwostok')
1373 < three one wladiwostok ~
1375 Notice that a ! was used to overwrite the existing function reference. Now
1376 use "uk2uk" when no recognized language is found: >
1380 :elseif $LANG =~ "nl"
1385 :echo trans.translate('one two three')
1388 For further reading see |Lists| and |Dictionaries|.
1390 ==============================================================================
1393 Let's start with an example: >
1396 : read ~/templates/pascal.tmpl
1398 : echo "Sorry, the Pascal template file cannot be found."
1401 The ":read" command will fail if the file does not exist. Instead of
1402 generating an error message, this code catches the error and gives the user a
1403 nice message instead.
1405 For the commands in between ":try" and ":endtry" errors are turned into
1406 exceptions. An exception is a string. In the case of an error the string
1407 contains the error message. And every error message has a number. In this
1408 case, the error we catch contains "E484:". This number is guaranteed to stay
1409 the same (the text may change, e.g., it may be translated).
1411 When the ":read" command causes another error, the pattern "E484:" will not
1412 match in it. Thus this exception will not be caught and result in the usual
1415 You might be tempted to do this: >
1418 : read ~/templates/pascal.tmpl
1420 : echo "Sorry, the Pascal template file cannot be found."
1423 This means all errors are caught. But then you will not see errors that are
1424 useful, such as "E21: Cannot make changes, 'modifiable' is off".
1426 Another useful mechanism is the ":finally" command: >
1428 :let tmp = tempname()
1430 : exe ".,$write " . tmp
1431 : exe "!filter " . tmp
1433 : exe "$read " . tmp
1438 This 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
1440 filtering works, something goes wrong in between ":try" and ":finally" or the
1441 user cancels the filtering by pressing CTRL-C, the "call delete(tmp)" is
1442 always executed. This makes sure you don't leave the temporary file behind.
1444 More information about exception handling can be found in the reference
1445 manual: |exception-handling|.
1447 ==============================================================================
1448 *41.10* Various remarks
1450 Here is a summary of items that apply to Vim scripts. They are also mentioned
1451 elsewhere, but form a nice checklist.
1453 The end-of-line character depends on the system. For Unix a single <NL>
1454 character is used. For MS-DOS, Windows, OS/2 and the like, <CR><LF> is used.
1455 This is important when using mappings that end in a <CR>. See |:source_crnl|.
1460 Blank lines are allowed and ignored.
1462 Leading whitespace characters (blanks and TABs) are always ignored. The
1463 whitespaces between parameters (e.g. between the 'set' and the 'cpoptions' in
1464 the example below) are reduced to one blank character and plays the role of a
1465 separator, the whitespaces after the last (visible) character may or may not
1466 be ignored depending on the situation, see below.
1468 For a ":set" command involving the "=" (equal) sign, such as in: >
1470 :set cpoptions =aABceFst
1472 the whitespace immediately before the "=" sign is ignored. But there can be
1473 no whitespace after the "=" sign!
1475 To include a whitespace character in the value of an option, it must be
1476 escaped by a "\" (backslash) as in the following example: >
1478 :set tags=my\ nice\ file
1480 The same example written as >
1482 :set tags=my nice file
1484 will issue an error, because it is interpreted as: >
1493 The character " (the double quote mark) starts a comment. Everything after
1494 and including this character until the end-of-line is considered a comment and
1495 is ignored, except for commands that don't consider comments, as shown in
1496 examples below. A comment can start on any character position on the line.
1498 There is a little "catch" with comments for some commands. Examples: >
1500 :abbrev dev development " shorthand
1501 :map <F3> o#include " insert include
1502 :execute cmd " do it
1503 :!ls *.c " list C files
1505 The abbreviation 'dev' will be expanded to 'development " shorthand'. The
1506 mapping of <F3> will actually be the whole line after the 'o# ....' including
1507 the '" insert include'. The "execute" command will give an error. The "!"
1508 command will send everything after it to the shell, causing an error for an
1509 unmatched '"' character.
1510 There can be no comment after ":map", ":abbreviate", ":execute" and "!"
1511 commands (there are a few more commands with this restriction). For the
1512 ":map", ":abbreviate" and ":execute" commands there is a trick: >
1514 :abbrev dev development|" shorthand
1515 :map <F3> o#include|" insert include
1516 :execute cmd |" do it
1518 With the '|' character the command is separated from the next one. And that
1519 next command is only a comment. For the last command you need to do two
1520 things: |:execute| and use '|': >
1521 :exe '!ls *.c' |" list C files
1523 Notice that there is no white space before the '|' in the abbreviation and
1524 mapping. For these commands, any character until the end-of-line or '|' is
1525 included. As a consequence of this behavior, you don't always see that
1526 trailing whitespace is included: >
1530 To spot these problems, you can set the 'list' option when editing vimrc
1533 For Unix there is one special way to comment a line, that allows making a Vim
1534 script executable: >
1535 #!/usr/bin/env vim -S
1536 echo "this is a Vim script"
1539 The "#" command by itself lists a line with the line number. Adding an
1540 exclamation mark changes it into doing nothing, so that you can add the shell
1541 command to execute the rest of the file. |:#!| |-S|
1546 Even bigger problem arises in the following example: >
1551 Here the unmap command will not work, because it tries to unmap ",ab ". This
1552 does not exist as a mapped sequence. An error will be issued, which is very
1553 hard to identify, because the ending whitespace character in ":unmap ,ab " is
1556 And this is the same as what happens when one uses a comment after an 'unmap'
1559 :unmap ,ab " comment
1561 Here the comment part will be ignored. However, Vim will try to unmap
1562 ',ab ', which does not exist. Rewrite it as: >
1564 :unmap ,ab| " comment
1569 Sometimes you want to make a change and go back to where cursor was.
1570 Restoring the relative position would also be nice, so that the same line
1571 appears at the top of the window.
1572 This example yanks the current line, puts it above the first line in the
1573 file and then restores the view: >
1575 map ,p 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
1591 To avoid your function names to interfere with functions that you get from
1592 others, 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.
1600 " This is the XXX package
1602 if exists("XXX_loaded")
1608 ... body of function ...
1612 ... body of function ...
1617 ==============================================================================
1618 *41.11* Writing a plugin *write-plugin*
1620 You can write a Vim script in such a way that many people can use it. This is
1621 called a plugin. Vim users can drop your script in their plugin directory and
1622 use its features right away |add-plugin|.
1624 There are actually two types of plugins:
1626 global plugins: For all types of files.
1627 filetype plugins: Only for files of a specific type.
1629 In this section the first type is explained. Most items are also relevant for
1630 writing filetype plugins. The specifics for filetype plugins are in the next
1631 section |write-filetype-plugin|.
1636 First of all you must choose a name for your plugin. The features provided
1637 by the plugin should be clear from its name. And it should be unlikely that
1638 someone else writes a plugin with the same name but which does something
1639 different. And please limit the name to 8 characters, to avoid problems on
1640 old Windows systems.
1642 A script that corrects typing mistakes could be called "typecorr.vim". We
1643 will use it here as an example.
1645 For the plugin to work for everybody, it should follow a few guidelines. This
1646 will be explained step-by-step. The complete example plugin is at the end.
1651 Let's start with the body of the plugin, the lines that do the actual work: >
1654 15 iabbrev otehr other
1655 16 iabbrev wnat want
1656 17 iabbrev synchronisation
1657 18 \ synchronization
1660 The actual list should be much longer, of course.
1662 The line numbers have only been added to explain a few things, don't put them
1663 in your plugin file!
1668 You will probably add new corrections to the plugin and soon have several
1669 versions laying around. And when distributing this file, people will want to
1670 know who wrote this wonderful plugin and where they can send remarks.
1671 Therefore, put a header at the top of your plugin: >
1673 1 " Vim global plugin for correcting typing mistakes
1674 2 " Last Change: 2000 Oct 15
1675 3 " Maintainer: Bram Moolenaar <Bram@vim.org>
1677 About copyright and licensing: Since plugins are very useful and it's hardly
1678 worth restricting their distribution, please consider making your plugin
1679 either public domain or use the Vim |license|. A short note about this near
1680 the top of the plugin should be sufficient. Example: >
1682 4 " License: This file is placed in the public domain.
1685 LINE CONTINUATION, AVOIDING SIDE EFFECTS *use-cpo-save*
1687 In line 18 above, the line-continuation mechanism is used |line-continuation|.
1688 Users with 'compatible' set will run into trouble here, they will get an error
1689 message. We can't just reset 'compatible', because that has a lot of side
1690 effects. To avoid this, we will set the 'cpoptions' option to its Vim default
1691 value and restore it later. That will allow the use of line-continuation and
1692 make the script work for most people. It is done like this: >
1694 11 let s:save_cpo = &cpo
1697 42 let &cpo = s:save_cpo
1699 We first store the old value of 'cpoptions' in the s:save_cpo variable. At
1700 the end of the plugin this value is restored.
1702 Notice that a script-local variable is used |s:var|. A global variable could
1703 already be in use for something else. Always use script-local variables for
1704 things that are only used in the script.
1709 It's possible that a user doesn't always want to load this plugin. Or the
1710 system administrator has dropped it in the system-wide plugin directory, but a
1711 user has his own plugin he wants to use. Then the user must have a chance to
1712 disable loading this specific plugin. This will make it possible: >
1714 6 if exists("g:loaded_typecorr")
1717 9 let g:loaded_typecorr = 1
1719 This also avoids that when the script is loaded twice it would cause error
1720 messages for redefining functions and cause trouble for autocommands that are
1723 The name is recommended to start with "loaded_" and then the file name of the
1724 plugin, literally. The "g:" is prepended just to avoid mistakes when using
1725 the variable in a function (without "g:" it would be a variable local to the
1728 Using "finish" stops Vim from reading the rest of the file, it's much quicker
1729 than using if-endif around the whole file.
1734 Now let's make the plugin more interesting: We will add a mapping that adds a
1735 correction for the word under the cursor. We could just pick a key sequence
1736 for this mapping, but the user might already use it for something else. To
1737 allow the user to define which keys a mapping in a plugin uses, the <Leader>
1740 22 map <unique> <Leader>a <Plug>TypecorrAdd
1742 The "<Plug>TypecorrAdd" thing will do the work, more about that further on.
1744 The user can set the "mapleader" variable to the key sequence that he wants
1745 this mapping to start with. Thus if the user has done: >
1749 the mapping will define "_a". If the user didn't do this, the default value
1750 will be used, which is a backslash. Then a map for "\a" will be defined.
1752 Note that <unique> is used, this will cause an error message if the mapping
1753 already happened to exist. |:map-<unique>|
1755 But what if the user wants to define his own key sequence? We can allow that
1756 with this mechanism: >
1758 21 if !hasmapto('<Plug>TypecorrAdd')
1759 22 map <unique> <Leader>a <Plug>TypecorrAdd
1762 This checks if a mapping to "<Plug>TypecorrAdd" already exists, and only
1763 defines the mapping from "<Leader>a" if it doesn't. The user then has a
1764 chance of putting this in his vimrc file: >
1766 map ,c <Plug>TypecorrAdd
1768 Then the mapped key sequence will be ",c" instead of "_a" or "\a".
1773 If a script gets longer, you often want to break up the work in pieces. You
1774 can use functions or mappings for this. But you don't want these functions
1775 and mappings to interfere with the ones from other scripts. For example, you
1776 could define a function Add(), but another script could try to define the same
1777 function. To avoid this, we define the function local to the script by
1778 prepending it with "s:".
1780 We will define a function that adds a new typing correction: >
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
1788 Now we can call the function s:Add() from within this script. If another
1789 script also defines s:Add(), it will be local to that script and can only
1790 be called from the script it was defined in. There can also be a global Add()
1791 function (without the "s:"), which is again another function.
1793 <SID> can be used with mappings. It generates a script ID, which identifies
1794 the current script. In our typing correction plugin we use it like this: >
1796 24 noremap <unique> <script> <Plug>TypecorrAdd <SID>Add
1798 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), 1)<CR>
1800 Thus when a user types "\a", this sequence is invoked: >
1802 \a -> <Plug>TypecorrAdd -> <SID>Add -> :call <SID>Add()
1804 If another script would also map <SID>Add, it would get another script ID and
1805 thus define another mapping.
1807 Note that instead of s:Add() we use <SID>Add() here. That is because the
1808 mapping is typed by the user, thus outside of the script. The <SID> is
1809 translated to the script ID, so that Vim knows in which script to look for
1812 This is a bit complicated, but it's required for the plugin to work together
1813 with other plugins. The basic rule is that you use <SID>Add() in mappings and
1814 s:Add() in other places (the script itself, autocommands, user commands).
1816 We can also add a menu entry to do the same as the mapping: >
1818 26 noremenu <script> Plugin.Add\ Correction <SID>Add
1820 The "Plugin" menu is recommended for adding menu items for plugins. In this
1821 case only one item is used. When adding more items, creating a submenu is
1822 recommended. For example, "Plugin.CVS" could be used for a plugin that offers
1823 CVS operations "Plugin.CVS.checkin", "Plugin.CVS.checkout", etc.
1825 Note that in line 28 ":noremap" is used to avoid that any other mappings cause
1826 trouble. Someone may have remapped ":call", for example. In line 24 we also
1827 use ":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
1829 script. |:map-<script>| The same is done in line 26 for ":noremenu".
1833 <SID> AND <Plug> *using-<Plug>*
1835 Both <SID> and <Plug> are used to avoid that mappings of typed keys interfere
1836 with mappings that are only to be used from other mappings. Note the
1837 difference between using <SID> and <Plug>:
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
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.
1860 Now let's add a user command to add a correction: >
1862 38 if !exists(":Correct")
1863 39 command -nargs=1 Correct :call s:Add(<q-args>, 0)
1866 The user command is defined only if no command with the same name already
1867 exists. Otherwise we would get an error here. Overriding the existing user
1868 command with ":command!" is not a good idea, this would probably make the user
1869 wonder why the command he defined himself doesn't work. |:command|
1874 When a variable starts with "s:" it is a script variable. It can only be used
1875 inside a script. Outside the script it's not visible. This avoids trouble
1876 with using the same variable name in different scripts. The variables will be
1877 kept as long as Vim is running. And the same variables are used when sourcing
1878 the same script again. |s:var|
1880 The fun is that these variables can also be used in functions, autocommands
1881 and user commands that are defined in the script. In our example we can add
1882 a few lines to count the number of corrections: >
1886 30 function s:Add(from, correct)
1888 34 let s:count = s:count + 1
1889 35 echo s:count . " corrections now"
1892 First s:count is initialized to 4 in the script itself. When later the
1893 s:Add() function is called, it increments s:count. It doesn't matter from
1894 where the function was called, since it has been defined in the script, it
1895 will use the local variables from this script.
1900 Here is the resulting complete example: >
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.
1907 6 if exists("g:loaded_typecorr")
1910 9 let g:loaded_typecorr = 1
1912 11 let s:save_cpo = &cpo
1916 15 iabbrev otehr other
1917 16 iabbrev wnat want
1918 17 iabbrev synchronisation
1919 18 \ synchronization
1922 21 if !hasmapto('<Plug>TypecorrAdd')
1923 22 map <unique> <Leader>a <Plug>TypecorrAdd
1925 24 noremap <unique> <script> <Plug>TypecorrAdd <SID>Add
1927 26 noremenu <script> Plugin.Add\ Correction <SID>Add
1929 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), 1)<CR>
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"
1939 38 if !exists(":Correct")
1940 39 command -nargs=1 Correct :call s:Add(<q-args>, 0)
1943 42 let &cpo = s:save_cpo
1945 Line 33 wasn't explained yet. It applies the new correction to the word under
1946 the cursor. The |:normal| command is used to use the new abbreviation. Note
1947 that mappings and abbreviations are expanded here, even though the function
1948 was called from a mapping defined with ":noremap".
1950 Using "unix" for the 'fileformat' option is recommended. The Vim scripts will
1951 then work everywhere. Scripts with 'fileformat' set to "dos" do not work on
1952 Unix. Also see |:source_crnl|. To be sure it is set right, do this before
1955 :set fileformat=unix
1958 DOCUMENTATION *write-local-help*
1960 It's a good idea to also write some documentation for your plugin. Especially
1961 when its behavior can be changed by the user. See |add-local-help| for how
1964 Here is a simple example for a plugin help file, called "typecorr.txt": >
1966 1 *typecorr.txt* Plugin for correcting typing mistakes
1968 3 If you make typing mistakes, this plugin will have them corrected
1971 6 There are currently only a few corrections. Add your own if you like.
1974 9 <Leader>a or <Plug>TypecorrAdd
1975 10 Add a correction for the word under the cursor.
1979 14 Add a correction for {word}.
1981 16 *typecorr-settings*
1982 17 This plugin doesn't have any settings.
1984 The first line is actually the only one for which the format matters. It will
1985 be extracted from the help file to be put in the "LOCAL ADDITIONS:" section of
1986 help.txt |local-additions|. The first "*" must be in the first column of the
1987 first line. After adding your help file do ":help" and check that the entries
1990 You can add more tags inside ** in your help file. But be careful not to use
1991 existing help tags. You would probably use the name of your plugin in most of
1992 them, like "typecorr-settings" in the example.
1994 Using references to other parts of the help in || is recommended. This makes
1995 it easy for the user to find associated help.
1998 FILETYPE DETECTION *plugin-filetype*
2000 If your filetype is not already detected by Vim, you should create a filetype
2001 detection snippet in a separate file. It is usually in the form of an
2002 autocommand that sets the filetype when the file name matches a pattern.
2005 au BufNewFile,BufRead *.foo set filetype=foofoo
2007 Write this single-line file as "ftdetect/foofoo.vim" in the first directory
2008 that appears in 'runtimepath'. For Unix that would be
2009 "~/.vim/ftdetect/foofoo.vim". The convention is to use the name of the
2010 filetype for the script name.
2012 You can make more complicated checks if you like, for example to inspect the
2013 contents of the file to recognize the language. Also see |new-filetype|.
2016 SUMMARY *plugin-special*
2018 Summary of special things to use in a plugin:
2020 s:name Variables local to the script.
2022 <SID> Script-ID, used for mappings and functions local to
2025 hasmapto() Function to test if the user already defined a mapping
2026 for functionality the script offers.
2028 <Leader> Value of "mapleader", which the user defines as the
2029 keys that plugin mappings start with.
2031 :map <unique> Give a warning if a mapping already exists.
2033 :noremap <script> Use only mappings local to the script, not global
2036 exists(":Cmd") Check if a user command already exists.
2038 ==============================================================================
2039 *41.12* Writing a filetype plugin *write-filetype-plugin* *ftplugin*
2041 A filetype plugin is like a global plugin, except that it sets options and
2042 defines mappings for the current buffer only. See |add-filetype-plugin| for
2043 how this type of plugin is used.
2045 First read the section on global plugins above |41.11|. All that is said there
2046 also applies to filetype plugins. There are a few extras, which are explained
2047 here. The essential thing is that a filetype plugin should only have an
2048 effect on the current buffer.
2053 If you are writing a filetype plugin to be used by many people, they need a
2054 chance to disable loading it. Put this at the top of the plugin: >
2056 " Only do this when not done yet for this buffer
2057 if exists("b:did_ftplugin")
2060 let b:did_ftplugin = 1
2062 This also needs to be used to avoid that the same plugin is executed twice for
2063 the same buffer (happens when using an ":edit" command without arguments).
2065 Now users can disable loading the default plugin completely by making a
2066 filetype plugin with only this line: >
2068 let b:did_ftplugin = 1
2070 This does require that the filetype plugin directory comes before $VIMRUNTIME
2073 If you do want to use the default plugin, but overrule one of the settings,
2074 you can write the different setting in a script: >
2076 setlocal textwidth=70
2078 Now write this in the "after" directory, so that it gets sourced after the
2079 distributed "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.
2086 To make sure the filetype plugin only affects the current buffer use the >
2090 command to set options. And only set options which are local to a buffer (see
2091 the help for the option to check that). When using |:setlocal| for global
2092 options or options local to a window, the value will change for many buffers,
2093 and that is not what a filetype plugin should do.
2095 When 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
2097 changed an option value already. First resetting to the default value and
2098 then changing it often a good idea. Example: >
2100 :setlocal formatoptions& formatoptions+=ro
2105 To make sure mappings will only work in the current buffer use the >
2109 command. This needs to be combined with the two-step mapping explained above.
2110 An example of how to define functionality in a filetype plugin: >
2112 if !hasmapto('<Plug>JavaImport')
2113 map <buffer> <unique> <LocalLeader>i <Plug>JavaImport
2115 noremap <buffer> <unique> <Plug>JavaImport oimport ""<Left><Esc>
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
2119 mapping. This starts with |<LocalLeader>|, which allows the user to select
2120 the key(s) he wants filetype plugin mappings to start with. The default is a
2122 "<unique>" is used to give an error message if the mapping already exists or
2123 overlaps with an existing mapping.
2124 |:noremap| is used to avoid that any other mappings that the user has defined
2125 interferes. You might want to use ":noremap <script>" to allow remapping
2126 mappings defined in this script that start with <SID>.
2128 The user must have a chance to disable the mappings in a filetype plugin,
2129 without disabling everything. Here is an example of how this is done for a
2130 plugin for the mail filetype: >
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
2139 vnoremap <buffer> <Plug>MailQuote :s/^/> /<CR>
2140 nnoremap <buffer> <Plug>MailQuote :.,$s/^/> /<CR>
2143 Two global variables are used:
2144 no_plugin_maps disables mappings for all filetype plugins
2145 no_mail_maps disables mappings for a specific filetype
2150 To add a user command for a specific file type, so that it can only be used in
2151 one buffer, use the "-buffer" argument to |:command|. Example: >
2153 :command -buffer Make make %:r.s
2158 A filetype plugin will be sourced for each buffer of the type it's for. Local
2159 script variables |s:var| will be shared between all invocations. Use local
2160 buffer variables |b:var| if you want a variable specifically for one buffer.
2165 When defining a function, this only needs to be done once. But the filetype
2166 plugin will be sourced every time a file with this filetype will be opened.
2167 This construct makes sure the function is only defined once: >
2169 :if !exists("*s:Func")
2170 : function s:Func(arg)
2176 UNDO *undo_ftplugin*
2178 When the user does ":setfiletype xyz" the effect of the previous filetype
2179 should be undone. Set the b:undo_ftplugin variable to the commands that will
2180 undo the settings in your filetype plugin. Example: >
2182 let b:undo_ftplugin = "setlocal fo< com< tw< commentstring<"
2183 \ . "| unlet b:match_ignorecase b:match_words b:match_skip"
2185 Using ":setlocal" with "<" after the option name resets the option to its
2186 global value. That is mostly the best way to reset the option value.
2188 This does require removing the "C" flag from 'cpoptions' to allow line
2189 continuation, as mentioned above |use-cpo-save|.
2194 The filetype must be included in the file name |ftplugin-name|. Use one of
2197 .../ftplugin/stuff.vim
2198 .../ftplugin/stuff_foo.vim
2199 .../ftplugin/stuff/bar.vim
2201 "stuff" is the filetype, "foo" and "bar" are arbitrary names.
2204 SUMMARY *ftplugin-special*
2206 Summary of special things to use in a filetype plugin:
2208 <LocalLeader> Value of "maplocalleader", which the user defines as
2209 the keys that filetype plugin mappings start with.
2211 :map <buffer> Define a mapping local to the buffer.
2213 :noremap <script> Only remap mappings defined in this script that start
2216 :setlocal Set an option for the current buffer only.
2218 :command -buffer Define a user command local to the buffer.
2220 exists("*s:Func") Check if a function was already defined.
2222 Also see |plugin-special|, the special things used for all plugins.
2224 ==============================================================================
2225 *41.13* Writing a compiler plugin *write-compiler-plugin*
2227 A compiler plugin sets options for use with a specific compiler. The user can
2228 load it with the |:compiler| command. The main use is to set the
2229 'errorformat' and 'makeprg' options.
2231 Easiest is to have a look at examples. This command will edit all the default
2234 :next $VIMRUNTIME/compiler/*.vim
2236 Use |:next| to go to the next plugin file.
2238 There are two special items about these files. First is a mechanism to allow
2239 a user to overrule or add to the default file. The default files start with: >
2241 :if exists("current_compiler")
2244 :let current_compiler = "mine"
2246 When 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
2248 make the default file skip the settings.
2250 The second mechanism is to use ":set" for ":compiler!" and ":setlocal" for
2251 ":compiler". Vim defines the ":CompilerSet" user command for this. However,
2252 older Vim versions don't, thus your plugin should define it then. This is an
2255 if exists(":CompilerSet") != 2
2256 command -nargs=* CompilerSet setlocal <args>
2258 CompilerSet errorformat& " use the default 'errorformat'
2259 CompilerSet makeprg=nmake
2261 When you write a compiler plugin for the Vim distribution or for a system-wide
2262 runtime directory, use the mechanism mentioned above. When
2263 "current_compiler" was already set by a user plugin nothing will be done.
2265 When you write a compiler plugin to overrule settings from a default plugin,
2266 don't check "current_compiler". This plugin is supposed to be loaded
2267 last, thus it should be in a directory at the end of 'runtimepath'. For Unix
2268 that could be ~/.vim/after/compiler.
2270 ==============================================================================
2271 *41.14* Writing a plugin that loads quickly *write-plugin-quickload*
2273 A plugin may grow and become quite long. The startup delay may become
2274 noticeable, while you hardly ever use the plugin. Then it's time for a
2277 The basic idea is that the plugin is loaded twice. The first time user
2278 commands and mappings are defined that offer the functionality. The second
2279 time the functions that implement the functionality are defined.
2281 It may sound surprising that quickload means loading a script twice. What we
2282 mean is that it loads quickly the first time, postponing the bulk of the
2283 script to the second time, which only happens when you actually use it. When
2284 you always use the functionality it actually gets slower!
2286 Note that since Vim 7 there is an alternative: use the |autoload|
2287 functionality |41.15|.
2289 The following example shows how it's done: >
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.
2296 if !exists("s:did_load")
2297 command -nargs=* BNRead call BufNetRead(<f-args>)
2298 map <F19> :call BufNetWrite('something')<CR>
2301 exe 'au FuncUndefined BufNet* source ' . expand('<sfile>')
2305 function BufNetRead(...)
2306 echo 'BufNetRead(' . string(a:000) . ')'
2307 " read functionality here
2310 function BufNetWrite(...)
2311 echo 'BufNetWrite(' . string(a:000) . ')'
2312 " write functionality here
2315 When the script is first loaded "s:did_load" is not set. The commands between
2316 the "if" and "endif" will be executed. This ends in a |:finish| command, thus
2317 the rest of the script is not executed.
2319 The second time the script is loaded "s:did_load" exists and the commands
2320 after the "endif" are executed. This defines the (possible long)
2321 BufNetRead() and BufNetWrite() functions.
2323 If you drop this script in your plugin directory Vim will execute it on
2324 startup. This is the sequence of events that happens:
2326 1. 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.
2330 2. The user types the BNRead command or presses the <F19> key. The
2331 BufNetRead() or BufNetWrite() function will be called.
2333 3. 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()|).
2339 4. The script is sourced again, the "s:did_load" variable exists and the
2340 functions are defined.
2342 Notice that the functions that are loaded afterwards match the pattern in the
2343 |FuncUndefined| autocommand. You must make sure that no other plugin defines
2344 functions that match this pattern.
2346 ==============================================================================
2347 *41.15* Writing library scripts *write-library-script*
2349 Some functionality will be required in several places. When this becomes more
2350 than a few lines you will want to put it in one script and use it from many
2351 scripts. We will call that one script a library script.
2353 Manually loading a library script is possible, so long as you avoid loading it
2354 when it's already done. You can do this with the |exists()| function.
2357 if !exists('*MyLibFunction')
2358 runtime library/mylibscript.vim
2360 call MyLibFunction(arg)
2362 Here you need to know that MyLibFunction() is defined in a script
2363 "library/mylibscript.vim" in one of the directories in 'runtimepath'.
2365 To make this a bit simpler Vim offers the autoload mechanism. Then the
2366 example looks like this: >
2368 call mylib#myfunction(arg)
2370 That's a lot simpler, isn't it? Vim will recognize the function name and when
2371 it's not defined search for the script "autoload/mylib.vim" in 'runtimepath'.
2372 That script must define the "mylib#myfunction()" function.
2374 You can put many other functions in the mylib.vim script, you are free to
2375 organize your functions in library scripts. But you must use function names
2376 where the part before the '#' matches the script name. Otherwise Vim would
2377 not know what script to load.
2379 If you get really enthusiastic and write lots of library scripts, you may
2380 want to use subdirectories. Example: >
2382 call netlib#ftp#read('somefile')
2384 For Unix the library script used for this could be:
2386 ~/.vim/autoload/netlib/ftp.vim
2388 Where the function is defined like this: >
2390 function netlib#ftp#read(fname)
2391 " Read the file fname through ftp
2394 Notice that the name the function is defined with is exactly the same as the
2395 name used for calling the function. And the part before the last '#'
2396 exactly matches the subdirectory and script name.
2398 You can use the same mechanism for variables: >
2400 let weekdays = dutch#weekdays
2402 This will load the script "autoload/dutch.vim", which should contain something
2405 let dutch#weekdays = ['zondag', 'maandag', 'dinsdag', 'woensdag',
2406 \ 'donderdag', 'vrijdag', 'zaterdag']
2408 Further reading: |autoload|.
2410 ==============================================================================
2411 *41.16* Distributing Vim scripts *distribute-script*
2413 Vim users will look for scripts on the Vim website: http://www.vim.org.
2414 If you made something that is useful for others, share it!
2416 Vim scripts can be used on any system. There might not be a tar or gzip
2417 command. If you want to pack files together and/or compress them the "zip"
2418 utility is recommended.
2420 For utmost portability use Vim itself to pack scripts together. This can be
2421 done with the Vimball utility. See |vimball|.
2423 It's good if you add a line to allow automatic updating. See |glvs-plugins|.
2425 ==============================================================================
2427 Next chapter: |usr_42.txt| Add new menus
2429 Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: