blob: 5305ff18bcd595ce4b5dacd742d375545e0ae8aa [file] [log] [blame]
Bram Moolenaared39e1d2008-08-09 17:55:22 +00001*usr_41.txt* For Vim version 7.2. Last change: 2008 Jun 21
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
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
Bram Moolenaar7c626922005-02-07 22:01:03 +000019|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
Bram Moolenaar05159a02005-02-26 23:04:13 +000025|41.14| Writing a plugin that loads quickly
26|41.15| Writing library scripts
Bram Moolenaar76916e62006-03-21 21:23:25 +000027|41.16| Distributing Vim scripts
Bram Moolenaar071d4272004-06-13 20:20:40 +000028
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==============================================================================
Bram Moolenaar9d75c832005-01-25 21:57:23 +000034*41.1* Introduction *vim-script-intro* *script*
Bram Moolenaar071d4272004-06-13 20:20:40 +000035
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
Bram Moolenaar7c626922005-02-07 22:01:03 +000049 : let i += 1
Bram Moolenaar071d4272004-06-13 20:20:40 +000050 :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.
Bram Moolenaar7c626922005-02-07 22:01:03 +000057 Note:
58 You can try out the examples by yanking the lines from the text here
59 and executing them with :@"
Bram Moolenaar071d4272004-06-13 20:20:40 +000060
Bram Moolenaar7c626922005-02-07 22:01:03 +000061The 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: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000070
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.
Bram Moolenaar071d4272004-06-13 20:20:40 +000084 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
Bram Moolenaar7c626922005-02-07 22:01:03 +000088The ":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
Bram Moolenaaraf7f6412005-01-17 22:11:23 +000098make 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
Bram Moolenaar7c626922005-02-07 22:01:03 +0000104We won't explain how |:for| and |range()| work until later. Follow the links
105if you are impatient.
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000106
Bram Moolenaar071d4272004-06-13 20:20:40 +0000107
108THREE KINDS OF NUMBERS
109
110Numbers can be decimal, hexadecimal or octal. A hexadecimal number starts
Bram Moolenaar7c626922005-02-07 22:01:03 +0000111with "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!
Bram Moolenaar071d4272004-06-13 20:20:40 +0000114 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
Bram Moolenaar7c626922005-02-07 22:01:03 +0000120and octal numbers. A minus sign is also used for subtraction. Compare this
121with the previous example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000122
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
Bram Moolenaar7c626922005-02-07 22:01:03 +0000128avoid the confusion with a negative number above, put a space between the
129minus sign and the following number: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000130
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
Bram Moolenaar7c626922005-02-07 22:01:03 +0000160 : let s:count += 1
Bram Moolenaar071d4272004-06-13 20:20:40 +0000161 :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()".
Bram Moolenaar7c626922005-02-07 22:01:03 +0000211 What Vim calls true is anything that is not zero. Zero is false.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000212 Note:
Bram Moolenaar7c626922005-02-07 22:01:03 +0000213 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!
Bram Moolenaar071d4272004-06-13 20:20:40 +0000218
219
220STRING VARIABLES AND CONSTANTS
221
222So far only numbers were used for the variable value. Strings can be used as
Bram Moolenaar7c626922005-02-07 22:01:03 +0000223well. 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|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000226 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
Bram Moolenaar7c626922005-02-07 22:01:03 +0000246Inside 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
Bram Moolenaar071d4272004-06-13 20:20:40 +0000249character 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
Bram Moolenaar7c626922005-02-07 22:01:03 +0000296off. 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|.)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000298
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
Bram Moolenaar7c626922005-02-07 22:01:03 +0000403 :if v:version >= 700
Bram Moolenaar071d4272004-06-13 20:20:40 +0000404 : 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,
Bram Moolenaar7c626922005-02-07 22:01:03 +0000444because backslashes would need to be doubled in a double-quote string and
445patterns tend to contain many backslashes.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000446
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
Bram Moolenaar7c626922005-02-07 22:01:03 +0000480Even more looping can be done with the ":for" command, see below in |41.8|.
481
Bram Moolenaar071d4272004-06-13 20:20:40 +0000482==============================================================================
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
Bram Moolenaar7c626922005-02-07 22:01:03 +0000521If 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
Bram Moolenaar071d4272004-06-13 20:20:40 +0000532==============================================================================
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
Bram Moolenaar7c626922005-02-07 22:01:03 +0000555The 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.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000558 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:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000580 nr2char() get a character by its ASCII value
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000581 char2nr() get ASCII value of a character
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000582 str2nr() convert a string to a Number
583 str2float() convert a string to a Float
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000584 printf() format a string according to % items
Bram Moolenaar071d4272004-06-13 20:20:40 +0000585 escape() escape characters in a string with a '\'
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000586 shellescape() escape a string for use with a shell command
587 fnameescape() escape a file name for use with a Vim command
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000588 tr() translate characters from one set to another
Bram Moolenaar071d4272004-06-13 20:20:40 +0000589 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
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000595 matchlist() like matchstr() and also return submatches
Bram Moolenaar071d4272004-06-13 20:20:40 +0000596 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
Bram Moolenaar071d4272004-06-13 20:20:40 +0000603 iconv() convert text from one encoding to another
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000604 byteidx() byte index of a character in a string
605 repeat() repeat a string multiple times
606 eval() evaluate a string expression
Bram Moolenaar071d4272004-06-13 20:20:40 +0000607
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000608List manipulation:
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
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000624 range() return a List with a sequence of numbers
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000625 string() String representation of a List
626 call() call a function with List as arguments
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000627 index() index of a value in a List
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000628 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
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000631 repeat() repeat a List multiple times
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000632
633Dictionary manipulation:
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000634 get() get an entry without an error for a wrong key
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000635 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
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000652Floating point computation:
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
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000666Variables:
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
Bram Moolenaarc6249bb2006-04-15 20:25:09 +0000672 getwinvar() get a variable from specific window
673 gettabwinvar() get a variable from specific window & tab page
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000674 setwinvar() set a variable in a specific window
Bram Moolenaarc6249bb2006-04-15 20:25:09 +0000675 settabwinvar() set a variable in a specific window & tab page
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000676 garbagecollect() possibly free memory
677
678Cursor and mark position:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000679 col() column number of the cursor or a mark
680 virtcol() screen column of the cursor or a mark
681 line() line number of the cursor or mark
682 wincol() window column number of the cursor
683 winline() window line number of the cursor
684 cursor() position the cursor at a line/column
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000685 getpos() get position of cursor, mark, etc.
686 setpos() set position of cursor, mark, etc.
687 byte2line() get line number at a specific byte count
688 line2byte() byte count at a specific line
689 diff_filler() get the number of filler lines above a line
690
691Working with text in the current buffer:
Bram Moolenaar7c626922005-02-07 22:01:03 +0000692 getline() get a line or list of lines from the buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +0000693 setline() replace a line in the buffer
Bram Moolenaar7c626922005-02-07 22:01:03 +0000694 append() append line or list of lines in the buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +0000695 indent() indent of a specific line
696 cindent() indent according to C indenting
697 lispindent() indent according to Lisp indenting
698 nextnonblank() find next non-blank line
699 prevnonblank() find previous non-blank line
700 search() find a match for a pattern
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000701 searchpos() find a match for a pattern
Bram Moolenaar071d4272004-06-13 20:20:40 +0000702 searchpair() find the other end of a start/skip/end
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000703 searchpairpos() find the other end of a start/skip/end
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000704 searchdecl() search for the declaration of a name
Bram Moolenaar071d4272004-06-13 20:20:40 +0000705
706System functions and manipulation of files:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000707 glob() expand wildcards
708 globpath() expand wildcards in a number of directories
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000709 findfile() find a file in a list of directories
710 finddir() find a directory in a list of directories
Bram Moolenaar071d4272004-06-13 20:20:40 +0000711 resolve() find out where a shortcut points to
712 fnamemodify() modify a file name
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000713 pathshorten() shorten directory names in a path
714 simplify() simplify a path without changing its meaning
Bram Moolenaar071d4272004-06-13 20:20:40 +0000715 executable() check if an executable program exists
716 filereadable() check if a file can be read
717 filewritable() check if a file can be written to
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000718 getfperm() get the permissions of a file
719 getftype() get the kind of a file
Bram Moolenaar071d4272004-06-13 20:20:40 +0000720 isdirectory() check if a directory exists
Bram Moolenaar071d4272004-06-13 20:20:40 +0000721 getfsize() get the size of a file
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000722 getcwd() get the current working directory
Bram Moolenaard267b9c2007-04-26 15:06:45 +0000723 haslocaldir() check if current window used |:lcd|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000724 tempname() get the name of a temporary file
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000725 mkdir() create a new directory
Bram Moolenaar071d4272004-06-13 20:20:40 +0000726 delete() delete a file
727 rename() rename a file
728 system() get the result of a shell command
729 hostname() name of the system
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +0000730 readfile() read a file into a List of lines
731 writefile() write a List of lines into a file
Bram Moolenaar071d4272004-06-13 20:20:40 +0000732
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000733Date and Time:
734 getftime() get last modification time of a file
735 localtime() get current time in seconds
736 strftime() convert time to a string
737 reltime() get the current or elapsed time accurately
738 reltimestr() convert reltime() result to a string
739
Bram Moolenaar071d4272004-06-13 20:20:40 +0000740Buffers, windows and the argument list:
741 argc() number of entries in the argument list
742 argidx() current position in the argument list
743 argv() get one entry from the argument list
744 bufexists() check if a buffer exists
745 buflisted() check if a buffer exists and is listed
746 bufloaded() check if a buffer exists and is loaded
747 bufname() get the name of a specific buffer
748 bufnr() get the buffer number of a specific buffer
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000749 tabpagebuflist() return List of buffers in a tab page
750 tabpagenr() get the number of a tab page
751 tabpagewinnr() like winnr() for a specified tab page
Bram Moolenaar071d4272004-06-13 20:20:40 +0000752 winnr() get the window number for the current window
753 bufwinnr() get the window number of a specific buffer
754 winbufnr() get the buffer number of a specific window
Bram Moolenaara3ffd9c2005-07-21 21:03:15 +0000755 getbufline() get a list of lines from the specified buffer
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000756
757Command line:
758 getcmdline() get the current command line
759 getcmdpos() get position of the cursor in the command line
760 setcmdpos() set position of the cursor in the command line
761 getcmdtype() return the current command-line type
762
763Quickfix and location lists:
764 getqflist() list of quickfix errors
765 setqflist() modify a quickfix list
766 getloclist() list of location list items
767 setloclist() modify a location list
768
769Insert mode completion:
770 complete() set found matches
771 complete_add() add to found matches
772 complete_check() check if completion should be aborted
773 pumvisible() check if the popup menu is displayed
Bram Moolenaar071d4272004-06-13 20:20:40 +0000774
775Folding:
776 foldclosed() check for a closed fold at a specific line
777 foldclosedend() like foldclosed() but return the last line
778 foldlevel() check for the fold level at a specific line
779 foldtext() generate the line displayed for a closed fold
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000780 foldtextresult() get the text displayed for a closed fold
Bram Moolenaar071d4272004-06-13 20:20:40 +0000781
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000782Syntax and highlighting:
Bram Moolenaar6ee10162007-07-26 20:58:42 +0000783 clearmatches() clear all matches defined by |matchadd()| and
784 the |:match| commands
785 getmatches() get all matches defined by |matchadd()| and
786 the |:match| commands
Bram Moolenaar071d4272004-06-13 20:20:40 +0000787 hlexists() check if a highlight group exists
788 hlID() get ID of a highlight group
789 synID() get syntax ID at a specific position
790 synIDattr() get a specific attribute of a syntax ID
791 synIDtrans() get translated syntax ID
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000792 diff_hlID() get highlight ID for diff mode at a position
Bram Moolenaar6ee10162007-07-26 20:58:42 +0000793 matchadd() define a pattern to highlight (a "match")
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000794 matcharg() get info about |:match| arguments
Bram Moolenaar6ee10162007-07-26 20:58:42 +0000795 matchdelete() delete a match defined by |matchadd()| or a
796 |:match| command
797 setmatches() restore a list of matches saved by
798 |getmatches()|
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000799
800Spelling:
801 spellbadword() locate badly spelled word at or after cursor
802 spellsuggest() return suggested spelling corrections
803 soundfold() return the sound-a-like equivalent of a word
Bram Moolenaar071d4272004-06-13 20:20:40 +0000804
805History:
806 histadd() add an item to a history
807 histdel() delete an item from a history
808 histget() get an item from a history
809 histnr() get highest index of a history list
810
811Interactive:
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000812 browse() put up a file requester
813 browsedir() put up a directory requester
Bram Moolenaar071d4272004-06-13 20:20:40 +0000814 confirm() let the user make a choice
815 getchar() get a character from the user
816 getcharmod() get modifiers for the last typed character
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000817 feedkeys() put characters in the typeahead queue
Bram Moolenaar071d4272004-06-13 20:20:40 +0000818 input() get a line from the user
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000819 inputlist() let the user pick an entry from a list
Bram Moolenaar071d4272004-06-13 20:20:40 +0000820 inputsecret() get a line from the user without showing it
821 inputdialog() get a line from the user in a dialog
Bram Moolenaar68b76a62005-03-25 21:53:48 +0000822 inputsave() save and clear typeahead
Bram Moolenaar071d4272004-06-13 20:20:40 +0000823 inputrestore() restore typeahead
824
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000825GUI:
826 getfontname() get name of current font being used
827 getwinposx() X position of the GUI Vim window
828 getwinposy() Y position of the GUI Vim window
829
Bram Moolenaar071d4272004-06-13 20:20:40 +0000830Vim server:
831 serverlist() return the list of server names
832 remote_send() send command characters to a Vim server
833 remote_expr() evaluate an expression in a Vim server
834 server2client() send a reply to a client of a Vim server
835 remote_peek() check if there is a reply from a Vim server
836 remote_read() read a reply from a Vim server
837 foreground() move the Vim window to the foreground
838 remote_foreground() move the Vim server window to the foreground
839
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000840Window size and position:
841 winheight() get height of a specific window
842 winwidth() get width of a specific window
843 winrestcmd() return command to restore window sizes
844 winsaveview() get view of current window
845 winrestview() restore saved view of current window
846
Bram Moolenaar071d4272004-06-13 20:20:40 +0000847Various:
848 mode() get current editing mode
849 visualmode() last visual mode used
850 hasmapto() check if a mapping exists
851 mapcheck() check if a matching mapping exists
852 maparg() get rhs of a mapping
853 exists() check if a variable, function, etc. exists
854 has() check if a feature is supported in Vim
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000855 changenr() return number of most recent change
Bram Moolenaar071d4272004-06-13 20:20:40 +0000856 cscope_connection() check if a cscope connection exists
857 did_filetype() check if a FileType autocommand was used
858 eventhandler() check if invoked by an event handler
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000859 getpid() get process ID of Vim
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000860
Bram Moolenaar071d4272004-06-13 20:20:40 +0000861 libcall() call a function in an external library
862 libcallnr() idem, returning a number
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000863
Bram Moolenaar071d4272004-06-13 20:20:40 +0000864 getreg() get contents of a register
865 getregtype() get type of a register
866 setreg() set contents and type of a register
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000867
Bram Moolenaarda5d7402005-03-16 09:50:44 +0000868 taglist() get list of matching tags
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000869 tagfiles() get a list of tags files
Bram Moolenaar071d4272004-06-13 20:20:40 +0000870
871==============================================================================
872*41.7* Defining a function
873
874Vim enables you to define your own functions. The basic function declaration
875begins as follows: >
876
877 :function {name}({var1}, {var2}, ...)
878 : {body}
879 :endfunction
880<
881 Note:
882 Function names must begin with a capital letter.
883
884Let's define a short function to return the smaller of two numbers. It starts
885with this line: >
886
887 :function Min(num1, num2)
888
889This tells Vim that the function is named "Min" and it takes two arguments:
890"num1" and "num2".
891 The first thing you need to do is to check to see which number is smaller:
892 >
893 : if a:num1 < a:num2
894
895The special prefix "a:" tells Vim that the variable is a function argument.
896Let's assign the variable "smaller" the value of the smallest number: >
897
898 : if a:num1 < a:num2
899 : let smaller = a:num1
900 : else
901 : let smaller = a:num2
902 : endif
903
904The variable "smaller" is a local variable. Variables used inside a function
905are local unless prefixed by something like "g:", "a:", or "s:".
906
907 Note:
908 To access a global variable from inside a function you must prepend
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000909 "g:" to it. Thus "g:today" inside a function is used for the global
910 variable "today", and "today" is another variable, local to the
Bram Moolenaar071d4272004-06-13 20:20:40 +0000911 function.
912
913You now use the ":return" statement to return the smallest number to the user.
914Finally, you end the function: >
915
916 : return smaller
917 :endfunction
918
919The complete function definition is as follows: >
920
921 :function Min(num1, num2)
922 : if a:num1 < a:num2
923 : let smaller = a:num1
924 : else
925 : let smaller = a:num2
926 : endif
927 : return smaller
928 :endfunction
929
Bram Moolenaar7c626922005-02-07 22:01:03 +0000930For people who like short functions, this does the same thing: >
931
932 :function Min(num1, num2)
933 : if a:num1 < a:num2
934 : return a:num1
935 : endif
936 : return a:num2
937 :endfunction
938
Bram Moolenaard1f56e62006-02-22 21:25:37 +0000939A user defined function is called in exactly the same way as a built-in
Bram Moolenaar071d4272004-06-13 20:20:40 +0000940function. Only the name is different. The Min function can be used like
941this: >
942
943 :echo Min(5, 8)
944
945Only now will the function be executed and the lines be interpreted by Vim.
946If there are mistakes, like using an undefined variable or function, you will
947now get an error message. When defining the function these errors are not
948detected.
949
950When a function reaches ":endfunction" or ":return" is used without an
951argument, the function returns zero.
952
953To redefine a function that already exists, use the ! for the ":function"
954command: >
955
956 :function! Min(num1, num2, num3)
957
958
959USING A RANGE
960
961The ":call" command can be given a line range. This can have one of two
962meanings. When a function has been defined with the "range" keyword, it will
963take care of the line range itself.
964 The function will be passed the variables "a:firstline" and "a:lastline".
965These will have the line numbers from the range the function was called with.
966Example: >
967
968 :function Count_words() range
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000969 : let lnum = a:firstline
970 : let n = 0
971 : while lnum <= a:lastline
972 : let n = n + len(split(getline(lnum)))
973 : let lnum = lnum + 1
Bram Moolenaar071d4272004-06-13 20:20:40 +0000974 : endwhile
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000975 : echo "found " . n . " words"
Bram Moolenaar071d4272004-06-13 20:20:40 +0000976 :endfunction
977
978You can call this function with: >
979
980 :10,30call Count_words()
981
982It will be executed once and echo the number of words.
983 The other way to use a line range is by defining a function without the
984"range" keyword. The function will be called once for every line in the
985range, with the cursor in that line. Example: >
986
987 :function Number()
988 : echo "line " . line(".") . " contains: " . getline(".")
989 :endfunction
990
991If you call this function with: >
992
993 :10,15call Number()
994
995The function will be called six times.
996
997
998VARIABLE NUMBER OF ARGUMENTS
999
1000Vim enables you to define functions that have a variable number of arguments.
1001The following command, for instance, defines a function that must have 1
1002argument (start) and can have up to 20 additional arguments: >
1003
1004 :function Show(start, ...)
1005
1006The variable "a:1" contains the first optional argument, "a:2" the second, and
1007so on. The variable "a:0" contains the number of extra arguments.
1008 For example: >
1009
1010 :function Show(start, ...)
1011 : echohl Title
1012 : echo "Show is " . a:start
1013 : echohl None
1014 : let index = 1
1015 : while index <= a:0
1016 : echo " Arg " . index . " is " . a:{index}
1017 : let index = index + 1
1018 : endwhile
1019 : echo ""
1020 :endfunction
1021
1022This uses the ":echohl" command to specify the highlighting used for the
1023following ":echo" command. ":echohl None" stops it again. The ":echon"
1024command works like ":echo", but doesn't output a line break.
1025
Bram Moolenaar7c626922005-02-07 22:01:03 +00001026You can also use the a:000 variable, it is a List of all the "..." arguments.
1027See |a:000|.
1028
Bram Moolenaar071d4272004-06-13 20:20:40 +00001029
1030LISTING FUNCTIONS
1031
1032The ":function" command lists the names and arguments of all user-defined
1033functions: >
1034
1035 :function
1036< function Show(start, ...) ~
1037 function GetVimIndent() ~
1038 function SetSyn(name) ~
1039
1040To see what a function does, use its name as an argument for ":function": >
1041
1042 :function SetSyn
1043< 1 if &syntax == '' ~
1044 2 let &syntax = a:name ~
1045 3 endif ~
1046 endfunction ~
1047
1048
1049DEBUGGING
1050
1051The line number is useful for when you get an error message or when debugging.
1052See |debug-scripts| about debugging mode.
1053 You can also set the 'verbose' option to 12 or higher to see all function
1054calls. Set it to 15 or higher to see every executed line.
1055
1056
1057DELETING A FUNCTION
1058
1059To delete the Show() function: >
1060
1061 :delfunction Show
1062
1063You get an error when the function doesn't exist.
1064
Bram Moolenaar7c626922005-02-07 22:01:03 +00001065
1066FUNCTION REFERENCES
1067
1068Sometimes it can be useful to have a variable point to one function or
1069another. You can do it with the function() function. It turns the name of a
1070function into a reference: >
1071
1072 :let result = 0 " or 1
1073 :function! Right()
1074 : return 'Right!'
1075 :endfunc
1076 :function! Wrong()
1077 : return 'Wrong!'
1078 :endfunc
1079 :
1080 :if result == 1
1081 : let Afunc = function('Right')
1082 :else
1083 : let Afunc = function('Wrong')
1084 :endif
1085 :echo call(Afunc, [])
1086< Wrong! ~
1087
1088Note that the name of a variable that holds a function reference must start
1089with a capital. Otherwise it could be confused with the name of a builtin
1090function.
1091 The way to invoke a function that a variable refers to is with the call()
1092function. Its first argument is the function reference, the second argument
1093is a List with arguments.
1094
1095Function references are most useful in combination with a Dictionary, as is
1096explained in the next section.
1097
Bram Moolenaar071d4272004-06-13 20:20:40 +00001098==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00001099*41.8* Lists and Dictionaries
1100
1101So far we have used the basic types String and Number. Vim also supports two
1102composite types: List and Dictionary.
1103
1104A List is an ordered sequence of things. The things can be any kind of value,
1105thus you can make a List of numbers, a List of Lists and even a List of mixed
1106items. To create a List with three strings: >
1107
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001108 :let alist = ['aap', 'mies', 'noot']
Bram Moolenaar7c626922005-02-07 22:01:03 +00001109
1110The List items are enclosed in square brackets and separated by commas. To
1111create an empty List: >
1112
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001113 :let alist = []
Bram Moolenaar7c626922005-02-07 22:01:03 +00001114
1115You can add items to a List with the add() function: >
1116
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001117 :let alist = []
Bram Moolenaar7c626922005-02-07 22:01:03 +00001118 :call add(alist, 'foo')
1119 :call add(alist, 'bar')
1120 :echo alist
1121< ['foo', 'bar'] ~
1122
1123List concatenation is done with +: >
1124
1125 :echo alist + ['foo', 'bar']
1126< ['foo', 'bar', 'foo', 'bar'] ~
1127
1128Or, if you want to extend a List directly: >
1129
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001130 :let alist = ['one']
Bram Moolenaar7c626922005-02-07 22:01:03 +00001131 :call extend(alist, ['two', 'three'])
1132 :echo alist
1133< ['one', 'two', 'three'] ~
1134
1135Notice that using add() will have a different effect: >
1136
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001137 :let alist = ['one']
Bram Moolenaar7c626922005-02-07 22:01:03 +00001138 :call add(alist, ['two', 'three'])
1139 :echo alist
1140< ['one', ['two', 'three']] ~
1141
1142The second argument of add() is added as a single item.
1143
1144
1145FOR LOOP
1146
1147One of the nice things you can do with a List is iterate over it: >
1148
1149 :let alist = ['one', 'two', 'three']
1150 :for n in alist
1151 : echo n
1152 :endfor
1153< one ~
1154 two ~
1155 three ~
1156
1157This will loop over each element in List "alist", assigning the value to
1158variable "n". The generic form of a for loop is: >
1159
1160 :for {varname} in {listexpression}
1161 : {commands}
1162 :endfor
1163
1164To loop a certain number of times you need a List of a specific length. The
1165range() function creates one for you: >
1166
1167 :for a in range(3)
1168 : echo a
1169 :endfor
1170< 0 ~
1171 1 ~
1172 2 ~
1173
1174Notice that the first item of the List that range() produces is zero, thus the
1175last item is one less than the length of the list.
1176 You can also specify the maximum value, the stride and even go backwards: >
1177
1178 :for a in range(8, 4, -2)
1179 : echo a
1180 :endfor
1181< 8 ~
1182 6 ~
1183 4 ~
1184
1185A more useful example, looping over lines in the buffer: >
1186
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001187 :for line in getline(1, 20)
1188 : if line =~ "Date: "
1189 : echo matchstr(line, 'Date: \zs.*')
1190 : endif
1191 :endfor
Bram Moolenaar7c626922005-02-07 22:01:03 +00001192
1193This looks into lines 1 to 20 (inclusive) and echoes any date found in there.
1194
1195
1196DICTIONARIES
1197
1198A Dictionary stores key-value pairs. You can quickly lookup a value if you
1199know the key. A Dictionary is created with curly braces: >
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001200
Bram Moolenaar7c626922005-02-07 22:01:03 +00001201 :let uk2nl = {'one': 'een', 'two': 'twee', 'three': 'drie'}
1202
Bram Moolenaar4399ef42005-02-12 14:29:27 +00001203Now you can lookup words by putting the key in square brackets: >
Bram Moolenaar7c626922005-02-07 22:01:03 +00001204
1205 :echo uk2nl['two']
1206< twee ~
1207
1208The generic form for defining a Dictionary is: >
1209
1210 {<key> : <value>, ...}
1211
1212An empty Dictionary is one without any keys: >
1213
1214 {}
1215
1216The possibilities with Dictionaries are numerous. There are various functions
1217for them as well. For example, you can obtain a list of the keys and loop
1218over them: >
1219
1220 :for key in keys(uk2nl)
1221 : echo key
1222 :endfor
1223< three ~
1224 one ~
1225 two ~
1226
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00001227You will notice the keys are not ordered. You can sort the list to get a
Bram Moolenaar7c626922005-02-07 22:01:03 +00001228specific order: >
1229
1230 :for key in sort(keys(uk2nl))
1231 : echo key
1232 :endfor
1233< one ~
1234 three ~
1235 two ~
1236
1237But you can never get back the order in which items are defined. For that you
1238need to use a List, it stores items in an ordered sequence.
1239
1240
1241DICTIONARY FUNCTIONS
1242
1243The items in a Dictionary can normally be obtained with an index in square
1244brackets: >
1245
1246 :echo uk2nl['one']
1247< een ~
1248
1249A method that does the same, but without so many punctuation characters: >
1250
1251 :echo uk2nl.one
1252< een ~
1253
1254This only works for a key that is made of ASCII letters, digits and the
1255underscore. You can also assign a new value this way: >
1256
1257 :let uk2nl.four = 'vier'
1258 :echo uk2nl
1259< {'three': 'drie', 'four': 'vier', 'one': 'een', 'two': 'twee'} ~
1260
1261And now for something special: you can directly define a function and store a
1262reference to it in the dictionary: >
1263
1264 :function uk2nl.translate(line) dict
1265 : return join(map(split(a:line), 'get(self, v:val, "???")'))
1266 :endfunction
1267
1268Let's first try it out: >
1269
1270 :echo uk2nl.translate('three two five one')
1271< drie twee ??? een ~
1272
1273The first special thing you notice is the "dict" at the end of the ":function"
1274line. This marks the function as being used from a Dictionary. The "self"
1275local variable will then refer to that Dictionary.
1276 Now let's break up the complicated return command: >
1277
1278 split(a:line)
1279
1280The split() function takes a string, chops it into white separated words
1281and returns a list with these words. Thus in the example it returns: >
1282
1283 :echo split('three two five one')
1284< ['three', 'two', 'five', 'one'] ~
1285
1286This list is the first argument to the map() function. This will go through
1287the list, evaluating its second argument with "v:val" set to the value of each
1288item. This is a shortcut to using a for loop. This command: >
1289
1290 :let alist = map(split(a:line), 'get(self, v:val, "???")')
1291
1292Is equivalent to: >
1293
1294 :let alist = split(a:line)
1295 :for idx in range(len(alist))
1296 : let alist[idx] = get(self, alist[idx], "???")
1297 :endfor
1298
1299The get() function checks if a key is present in a Dictionary. If it is, then
1300the value is retrieved. If it isn't, then the default value is returned, in
Bram Moolenaar4399ef42005-02-12 14:29:27 +00001301the example it's '???'. This is a convenient way to handle situations where a
Bram Moolenaar7c626922005-02-07 22:01:03 +00001302key may not be present and you don't want an error message.
1303
1304The join() function does the opposite of split(): it joins together a list of
1305words, putting a space in between.
1306 This combination of split(), map() and join() is a nice way to filter a line
1307of words in a very compact way.
1308
1309
1310OBJECT ORIENTED PROGRAMMING
1311
1312Now that you can put both values and functions in a Dictionary, you can
1313actually use a Dictionary like an object.
1314 Above we used a Dictionary for translating Dutch to English. We might want
1315to do the same for other languages. Let's first make an object (aka
1316Dictionary) that has the translate function, but no words to translate: >
1317
1318 :let transdict = {}
1319 :function transdict.translate(line) dict
1320 : return join(map(split(a:line), 'get(self.words, v:val, "???")'))
1321 :endfunction
1322
1323It's slightly different from the function above, using 'self.words' to lookup
1324word translations. But we don't have a self.words. Thus you could call this
1325an abstract class.
1326
1327Now we can instantiate a Dutch translation object: >
1328
1329 :let uk2nl = copy(transdict)
1330 :let uk2nl.words = {'one': 'een', 'two': 'twee', 'three': 'drie'}
1331 :echo uk2nl.translate('three one')
1332< drie een ~
1333
1334And a German translator: >
1335
1336 :let uk2de = copy(transdict)
1337 :let uk2de.words = {'one': 'ein', 'two': 'zwei', 'three': 'drei'}
1338 :echo uk2de.translate('three one')
1339< drei ein ~
1340
1341You see that the copy() function is used to make a copy of the "transdict"
1342Dictionary and then the copy is changed to add the words. The original
1343remains the same, of course.
1344
1345Now you can go one step further, and use your preferred translator: >
1346
1347 :if $LANG =~ "de"
1348 : let trans = uk2de
1349 :else
1350 : let trans = uk2nl
1351 :endif
1352 :echo trans.translate('one two three')
1353< een twee drie ~
1354
1355Here "trans" refers to one of the two objects (Dictionaries). No copy is
1356made. More about List and Dictionary identity can be found at |list-identity|
1357and |dict-identity|.
1358
1359Now you might use a language that isn't supported. You can overrule the
1360translate() function to do nothing: >
1361
1362 :let uk2uk = copy(transdict)
1363 :function! uk2uk.translate(line)
1364 : return a:line
1365 :endfunction
1366 :echo uk2uk.translate('three one wladiwostok')
1367< three one wladiwostok ~
1368
1369Notice that a ! was used to overwrite the existing function reference. Now
1370use "uk2uk" when no recognized language is found: >
1371
1372 :if $LANG =~ "de"
1373 : let trans = uk2de
1374 :elseif $LANG =~ "nl"
1375 : let trans = uk2nl
1376 :else
1377 : let trans = uk2uk
1378 :endif
1379 :echo trans.translate('one two three')
1380< one two three ~
1381
1382For further reading see |Lists| and |Dictionaries|.
1383
1384==============================================================================
1385*41.9* Exceptions
Bram Moolenaar071d4272004-06-13 20:20:40 +00001386
1387Let's start with an example: >
1388
1389 :try
1390 : read ~/templates/pascal.tmpl
1391 :catch /E484:/
1392 : echo "Sorry, the Pascal template file cannot be found."
1393 :endtry
1394
1395The ":read" command will fail if the file does not exist. Instead of
1396generating an error message, this code catches the error and gives the user a
1397nice message instead.
1398
1399For the commands in between ":try" and ":endtry" errors are turned into
1400exceptions. An exception is a string. In the case of an error the string
1401contains the error message. And every error message has a number. In this
1402case, the error we catch contains "E484:". This number is guaranteed to stay
1403the same (the text may change, e.g., it may be translated).
1404
1405When the ":read" command causes another error, the pattern "E484:" will not
1406match in it. Thus this exception will not be caught and result in the usual
1407error message.
1408
1409You might be tempted to do this: >
1410
1411 :try
1412 : read ~/templates/pascal.tmpl
1413 :catch
1414 : echo "Sorry, the Pascal template file cannot be found."
1415 :endtry
1416
1417This means all errors are caught. But then you will not see errors that are
1418useful, such as "E21: Cannot make changes, 'modifiable' is off".
1419
1420Another useful mechanism is the ":finally" command: >
1421
1422 :let tmp = tempname()
1423 :try
1424 : exe ".,$write " . tmp
1425 : exe "!filter " . tmp
1426 : .,$delete
1427 : exe "$read " . tmp
1428 :finally
1429 : call delete(tmp)
1430 :endtry
1431
1432This filters the lines from the cursor until the end of the file through the
1433"filter" command, which takes a file name argument. No matter if the
1434filtering works, something goes wrong in between ":try" and ":finally" or the
1435user cancels the filtering by pressing CTRL-C, the "call delete(tmp)" is
1436always executed. This makes sure you don't leave the temporary file behind.
1437
1438More information about exception handling can be found in the reference
1439manual: |exception-handling|.
1440
1441==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00001442*41.10* Various remarks
Bram Moolenaar071d4272004-06-13 20:20:40 +00001443
1444Here is a summary of items that apply to Vim scripts. They are also mentioned
1445elsewhere, but form a nice checklist.
1446
1447The end-of-line character depends on the system. For Unix a single <NL>
1448character is used. For MS-DOS, Windows, OS/2 and the like, <CR><LF> is used.
1449This is important when using mappings that end in a <CR>. See |:source_crnl|.
1450
1451
1452WHITE SPACE
1453
1454Blank lines are allowed and ignored.
1455
1456Leading whitespace characters (blanks and TABs) are always ignored. The
1457whitespaces between parameters (e.g. between the 'set' and the 'cpoptions' in
1458the example below) are reduced to one blank character and plays the role of a
1459separator, the whitespaces after the last (visible) character may or may not
1460be ignored depending on the situation, see below.
1461
1462For a ":set" command involving the "=" (equal) sign, such as in: >
1463
1464 :set cpoptions =aABceFst
1465
1466the whitespace immediately before the "=" sign is ignored. But there can be
1467no whitespace after the "=" sign!
1468
1469To include a whitespace character in the value of an option, it must be
1470escaped by a "\" (backslash) as in the following example: >
1471
1472 :set tags=my\ nice\ file
1473
1474The same example written as >
1475
1476 :set tags=my nice file
1477
1478will issue an error, because it is interpreted as: >
1479
1480 :set tags=my
1481 :set nice
1482 :set file
1483
1484
1485COMMENTS
1486
1487The character " (the double quote mark) starts a comment. Everything after
1488and including this character until the end-of-line is considered a comment and
1489is ignored, except for commands that don't consider comments, as shown in
1490examples below. A comment can start on any character position on the line.
1491
1492There is a little "catch" with comments for some commands. Examples: >
1493
1494 :abbrev dev development " shorthand
1495 :map <F3> o#include " insert include
1496 :execute cmd " do it
1497 :!ls *.c " list C files
1498
1499The abbreviation 'dev' will be expanded to 'development " shorthand'. The
1500mapping of <F3> will actually be the whole line after the 'o# ....' including
1501the '" insert include'. The "execute" command will give an error. The "!"
1502command will send everything after it to the shell, causing an error for an
1503unmatched '"' character.
1504 There can be no comment after ":map", ":abbreviate", ":execute" and "!"
1505commands (there are a few more commands with this restriction). For the
1506":map", ":abbreviate" and ":execute" commands there is a trick: >
1507
1508 :abbrev dev development|" shorthand
1509 :map <F3> o#include|" insert include
1510 :execute cmd |" do it
1511
1512With the '|' character the command is separated from the next one. And that
Bram Moolenaar9e1d2832007-05-06 12:51:41 +00001513next command is only a comment. For the last command you need to do two
1514things: |:execute| and use '|': >
1515 :exe '!ls *.c' |" list C files
Bram Moolenaar071d4272004-06-13 20:20:40 +00001516
1517Notice that there is no white space before the '|' in the abbreviation and
1518mapping. For these commands, any character until the end-of-line or '|' is
1519included. As a consequence of this behavior, you don't always see that
1520trailing whitespace is included: >
1521
1522 :map <F4> o#include
1523
Bram Moolenaar9e1d2832007-05-06 12:51:41 +00001524To spot these problems, you can set the 'list' option when editing vimrc
Bram Moolenaar071d4272004-06-13 20:20:40 +00001525files.
1526
Bram Moolenaar9e1d2832007-05-06 12:51:41 +00001527For Unix there is one special way to comment a line, that allows making a Vim
1528script executable: >
1529 #!/usr/bin/env vim -S
1530 echo "this is a Vim script"
1531 quit
1532
1533The "#" command by itself lists a line with the line number. Adding an
1534exclamation mark changes it into doing nothing, so that you can add the shell
1535command to execute the rest of the file. |:#!| |-S|
1536
Bram Moolenaar071d4272004-06-13 20:20:40 +00001537
1538PITFALLS
1539
1540Even bigger problem arises in the following example: >
1541
1542 :map ,ab o#include
1543 :unmap ,ab
1544
1545Here the unmap command will not work, because it tries to unmap ",ab ". This
1546does not exist as a mapped sequence. An error will be issued, which is very
1547hard to identify, because the ending whitespace character in ":unmap ,ab " is
1548not visible.
1549
1550And this is the same as what happens when one uses a comment after an 'unmap'
1551command: >
1552
1553 :unmap ,ab " comment
1554
1555Here the comment part will be ignored. However, Vim will try to unmap
1556',ab ', which does not exist. Rewrite it as: >
1557
1558 :unmap ,ab| " comment
1559
1560
1561RESTORING THE VIEW
1562
1563Sometimes you want to make a change and go back to where cursor was.
1564Restoring the relative position would also be nice, so that the same line
1565appears at the top of the window.
1566 This example yanks the current line, puts it above the first line in the
1567file and then restores the view: >
1568
1569 map ,p ma"aYHmbgg"aP`bzt`a
1570
1571What this does: >
1572 ma"aYHmbgg"aP`bzt`a
1573< ma set mark a at cursor position
1574 "aY yank current line into register a
1575 Hmb go to top line in window and set mark b there
1576 gg go to first line in file
1577 "aP put the yanked line above it
1578 `b go back to top line in display
1579 zt position the text in the window as before
1580 `a go back to saved cursor position
1581
1582
1583PACKAGING
1584
1585To avoid your function names to interfere with functions that you get from
1586others, use this scheme:
1587- Prepend a unique string before each function name. I often use an
1588 abbreviation. For example, "OW_" is used for the option window functions.
1589- Put the definition of your functions together in a file. Set a global
1590 variable to indicate that the functions have been loaded. When sourcing the
1591 file again, first unload the functions.
1592Example: >
1593
1594 " This is the XXX package
1595
1596 if exists("XXX_loaded")
1597 delfun XXX_one
1598 delfun XXX_two
1599 endif
1600
1601 function XXX_one(a)
1602 ... body of function ...
1603 endfun
1604
1605 function XXX_two(b)
1606 ... body of function ...
1607 endfun
1608
1609 let XXX_loaded = 1
1610
1611==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00001612*41.11* Writing a plugin *write-plugin*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001613
1614You can write a Vim script in such a way that many people can use it. This is
1615called a plugin. Vim users can drop your script in their plugin directory and
1616use its features right away |add-plugin|.
1617
1618There are actually two types of plugins:
1619
1620 global plugins: For all types of files.
1621filetype plugins: Only for files of a specific type.
1622
1623In this section the first type is explained. Most items are also relevant for
1624writing filetype plugins. The specifics for filetype plugins are in the next
1625section |write-filetype-plugin|.
1626
1627
1628NAME
1629
1630First of all you must choose a name for your plugin. The features provided
1631by the plugin should be clear from its name. And it should be unlikely that
1632someone else writes a plugin with the same name but which does something
1633different. And please limit the name to 8 characters, to avoid problems on
1634old Windows systems.
1635
1636A script that corrects typing mistakes could be called "typecorr.vim". We
1637will use it here as an example.
1638
1639For the plugin to work for everybody, it should follow a few guidelines. This
1640will be explained step-by-step. The complete example plugin is at the end.
1641
1642
1643BODY
1644
1645Let's start with the body of the plugin, the lines that do the actual work: >
1646
1647 14 iabbrev teh the
1648 15 iabbrev otehr other
1649 16 iabbrev wnat want
1650 17 iabbrev synchronisation
1651 18 \ synchronization
1652 19 let s:count = 4
1653
1654The actual list should be much longer, of course.
1655
1656The line numbers have only been added to explain a few things, don't put them
1657in your plugin file!
1658
1659
1660HEADER
1661
1662You will probably add new corrections to the plugin and soon have several
1663versions laying around. And when distributing this file, people will want to
1664know who wrote this wonderful plugin and where they can send remarks.
1665Therefore, put a header at the top of your plugin: >
1666
1667 1 " Vim global plugin for correcting typing mistakes
1668 2 " Last Change: 2000 Oct 15
1669 3 " Maintainer: Bram Moolenaar <Bram@vim.org>
1670
1671About copyright and licensing: Since plugins are very useful and it's hardly
1672worth restricting their distribution, please consider making your plugin
1673either public domain or use the Vim |license|. A short note about this near
1674the top of the plugin should be sufficient. Example: >
1675
1676 4 " License: This file is placed in the public domain.
1677
1678
1679LINE CONTINUATION, AVOIDING SIDE EFFECTS *use-cpo-save*
1680
1681In line 18 above, the line-continuation mechanism is used |line-continuation|.
1682Users with 'compatible' set will run into trouble here, they will get an error
1683message. We can't just reset 'compatible', because that has a lot of side
1684effects. To avoid this, we will set the 'cpoptions' option to its Vim default
1685value and restore it later. That will allow the use of line-continuation and
1686make the script work for most people. It is done like this: >
1687
1688 11 let s:save_cpo = &cpo
1689 12 set cpo&vim
1690 ..
1691 42 let &cpo = s:save_cpo
1692
1693We first store the old value of 'cpoptions' in the s:save_cpo variable. At
1694the end of the plugin this value is restored.
1695
1696Notice that a script-local variable is used |s:var|. A global variable could
1697already be in use for something else. Always use script-local variables for
1698things that are only used in the script.
1699
1700
1701NOT LOADING
1702
1703It's possible that a user doesn't always want to load this plugin. Or the
1704system administrator has dropped it in the system-wide plugin directory, but a
1705user has his own plugin he wants to use. Then the user must have a chance to
1706disable loading this specific plugin. This will make it possible: >
1707
1708 6 if exists("loaded_typecorr")
1709 7 finish
1710 8 endif
1711 9 let loaded_typecorr = 1
1712
1713This also avoids that when the script is loaded twice it would cause error
1714messages for redefining functions and cause trouble for autocommands that are
1715added twice.
1716
1717
1718MAPPING
1719
1720Now let's make the plugin more interesting: We will add a mapping that adds a
1721correction for the word under the cursor. We could just pick a key sequence
1722for this mapping, but the user might already use it for something else. To
1723allow the user to define which keys a mapping in a plugin uses, the <Leader>
1724item can be used: >
1725
1726 22 map <unique> <Leader>a <Plug>TypecorrAdd
1727
1728The "<Plug>TypecorrAdd" thing will do the work, more about that further on.
1729
1730The user can set the "mapleader" variable to the key sequence that he wants
1731this mapping to start with. Thus if the user has done: >
1732
1733 let mapleader = "_"
1734
1735the mapping will define "_a". If the user didn't do this, the default value
1736will be used, which is a backslash. Then a map for "\a" will be defined.
1737
1738Note that <unique> is used, this will cause an error message if the mapping
1739already happened to exist. |:map-<unique>|
1740
1741But what if the user wants to define his own key sequence? We can allow that
1742with this mechanism: >
1743
1744 21 if !hasmapto('<Plug>TypecorrAdd')
1745 22 map <unique> <Leader>a <Plug>TypecorrAdd
1746 23 endif
1747
1748This checks if a mapping to "<Plug>TypecorrAdd" already exists, and only
1749defines the mapping from "<Leader>a" if it doesn't. The user then has a
1750chance of putting this in his vimrc file: >
1751
1752 map ,c <Plug>TypecorrAdd
1753
1754Then the mapped key sequence will be ",c" instead of "_a" or "\a".
1755
1756
1757PIECES
1758
1759If a script gets longer, you often want to break up the work in pieces. You
1760can use functions or mappings for this. But you don't want these functions
1761and mappings to interfere with the ones from other scripts. For example, you
1762could define a function Add(), but another script could try to define the same
1763function. To avoid this, we define the function local to the script by
1764prepending it with "s:".
1765
1766We will define a function that adds a new typing correction: >
1767
1768 30 function s:Add(from, correct)
1769 31 let to = input("type the correction for " . a:from . ": ")
1770 32 exe ":iabbrev " . a:from . " " . to
1771 ..
1772 36 endfunction
1773
1774Now we can call the function s:Add() from within this script. If another
1775script also defines s:Add(), it will be local to that script and can only
1776be called from the script it was defined in. There can also be a global Add()
1777function (without the "s:"), which is again another function.
1778
1779<SID> can be used with mappings. It generates a script ID, which identifies
1780the current script. In our typing correction plugin we use it like this: >
1781
1782 24 noremap <unique> <script> <Plug>TypecorrAdd <SID>Add
1783 ..
1784 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), 1)<CR>
1785
1786Thus when a user types "\a", this sequence is invoked: >
1787
1788 \a -> <Plug>TypecorrAdd -> <SID>Add -> :call <SID>Add()
1789
1790If another script would also map <SID>Add, it would get another script ID and
1791thus define another mapping.
1792
1793Note that instead of s:Add() we use <SID>Add() here. That is because the
1794mapping is typed by the user, thus outside of the script. The <SID> is
1795translated to the script ID, so that Vim knows in which script to look for
1796the Add() function.
1797
1798This is a bit complicated, but it's required for the plugin to work together
1799with other plugins. The basic rule is that you use <SID>Add() in mappings and
1800s:Add() in other places (the script itself, autocommands, user commands).
1801
1802We can also add a menu entry to do the same as the mapping: >
1803
1804 26 noremenu <script> Plugin.Add\ Correction <SID>Add
1805
1806The "Plugin" menu is recommended for adding menu items for plugins. In this
1807case only one item is used. When adding more items, creating a submenu is
1808recommended. For example, "Plugin.CVS" could be used for a plugin that offers
1809CVS operations "Plugin.CVS.checkin", "Plugin.CVS.checkout", etc.
1810
1811Note that in line 28 ":noremap" is used to avoid that any other mappings cause
1812trouble. Someone may have remapped ":call", for example. In line 24 we also
1813use ":noremap", but we do want "<SID>Add" to be remapped. This is why
1814"<script>" is used here. This only allows mappings which are local to the
1815script. |:map-<script>| The same is done in line 26 for ":noremenu".
1816|:menu-<script>|
1817
1818
1819<SID> AND <Plug> *using-<Plug>*
1820
1821Both <SID> and <Plug> are used to avoid that mappings of typed keys interfere
1822with mappings that are only to be used from other mappings. Note the
1823difference between using <SID> and <Plug>:
1824
1825<Plug> is visible outside of the script. It is used for mappings which the
1826 user might want to map a key sequence to. <Plug> is a special code
1827 that a typed key will never produce.
1828 To make it very unlikely that other plugins use the same sequence of
1829 characters, use this structure: <Plug> scriptname mapname
1830 In our example the scriptname is "Typecorr" and the mapname is "Add".
1831 This results in "<Plug>TypecorrAdd". Only the first character of
1832 scriptname and mapname is uppercase, so that we can see where mapname
1833 starts.
1834
1835<SID> is the script ID, a unique identifier for a script.
1836 Internally Vim translates <SID> to "<SNR>123_", where "123" can be any
1837 number. Thus a function "<SID>Add()" will have a name "<SNR>11_Add()"
1838 in one script, and "<SNR>22_Add()" in another. You can see this if
1839 you use the ":function" command to get a list of functions. The
1840 translation of <SID> in mappings is exactly the same, that's how you
1841 can call a script-local function from a mapping.
1842
1843
1844USER COMMAND
1845
1846Now let's add a user command to add a correction: >
1847
1848 38 if !exists(":Correct")
1849 39 command -nargs=1 Correct :call s:Add(<q-args>, 0)
1850 40 endif
1851
1852The user command is defined only if no command with the same name already
1853exists. Otherwise we would get an error here. Overriding the existing user
1854command with ":command!" is not a good idea, this would probably make the user
1855wonder why the command he defined himself doesn't work. |:command|
1856
1857
1858SCRIPT VARIABLES
1859
1860When a variable starts with "s:" it is a script variable. It can only be used
1861inside a script. Outside the script it's not visible. This avoids trouble
1862with using the same variable name in different scripts. The variables will be
1863kept as long as Vim is running. And the same variables are used when sourcing
1864the same script again. |s:var|
1865
1866The fun is that these variables can also be used in functions, autocommands
1867and user commands that are defined in the script. In our example we can add
1868a few lines to count the number of corrections: >
1869
1870 19 let s:count = 4
1871 ..
1872 30 function s:Add(from, correct)
1873 ..
1874 34 let s:count = s:count + 1
1875 35 echo s:count . " corrections now"
1876 36 endfunction
1877
1878First s:count is initialized to 4 in the script itself. When later the
1879s:Add() function is called, it increments s:count. It doesn't matter from
1880where the function was called, since it has been defined in the script, it
1881will use the local variables from this script.
1882
1883
1884THE RESULT
1885
1886Here is the resulting complete example: >
1887
1888 1 " Vim global plugin for correcting typing mistakes
1889 2 " Last Change: 2000 Oct 15
1890 3 " Maintainer: Bram Moolenaar <Bram@vim.org>
1891 4 " License: This file is placed in the public domain.
1892 5
1893 6 if exists("loaded_typecorr")
1894 7 finish
1895 8 endif
1896 9 let loaded_typecorr = 1
1897 10
1898 11 let s:save_cpo = &cpo
1899 12 set cpo&vim
1900 13
1901 14 iabbrev teh the
1902 15 iabbrev otehr other
1903 16 iabbrev wnat want
1904 17 iabbrev synchronisation
1905 18 \ synchronization
1906 19 let s:count = 4
1907 20
1908 21 if !hasmapto('<Plug>TypecorrAdd')
1909 22 map <unique> <Leader>a <Plug>TypecorrAdd
1910 23 endif
1911 24 noremap <unique> <script> <Plug>TypecorrAdd <SID>Add
1912 25
1913 26 noremenu <script> Plugin.Add\ Correction <SID>Add
1914 27
1915 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), 1)<CR>
1916 29
1917 30 function s:Add(from, correct)
1918 31 let to = input("type the correction for " . a:from . ": ")
1919 32 exe ":iabbrev " . a:from . " " . to
1920 33 if a:correct | exe "normal viws\<C-R>\" \b\e" | endif
1921 34 let s:count = s:count + 1
1922 35 echo s:count . " corrections now"
1923 36 endfunction
1924 37
1925 38 if !exists(":Correct")
1926 39 command -nargs=1 Correct :call s:Add(<q-args>, 0)
1927 40 endif
1928 41
1929 42 let &cpo = s:save_cpo
1930
1931Line 33 wasn't explained yet. It applies the new correction to the word under
1932the cursor. The |:normal| command is used to use the new abbreviation. Note
1933that mappings and abbreviations are expanded here, even though the function
1934was called from a mapping defined with ":noremap".
1935
1936Using "unix" for the 'fileformat' option is recommended. The Vim scripts will
1937then work everywhere. Scripts with 'fileformat' set to "dos" do not work on
1938Unix. Also see |:source_crnl|. To be sure it is set right, do this before
1939writing the file: >
1940
1941 :set fileformat=unix
1942
1943
1944DOCUMENTATION *write-local-help*
1945
1946It's a good idea to also write some documentation for your plugin. Especially
1947when its behavior can be changed by the user. See |add-local-help| for how
1948they are installed.
1949
1950Here is a simple example for a plugin help file, called "typecorr.txt": >
1951
1952 1 *typecorr.txt* Plugin for correcting typing mistakes
1953 2
1954 3 If you make typing mistakes, this plugin will have them corrected
1955 4 automatically.
1956 5
1957 6 There are currently only a few corrections. Add your own if you like.
1958 7
1959 8 Mappings:
1960 9 <Leader>a or <Plug>TypecorrAdd
1961 10 Add a correction for the word under the cursor.
1962 11
1963 12 Commands:
1964 13 :Correct {word}
1965 14 Add a correction for {word}.
1966 15
1967 16 *typecorr-settings*
1968 17 This plugin doesn't have any settings.
1969
1970The first line is actually the only one for which the format matters. It will
1971be extracted from the help file to be put in the "LOCAL ADDITIONS:" section of
1972help.txt |local-additions|. The first "*" must be in the first column of the
1973first line. After adding your help file do ":help" and check that the entries
1974line up nicely.
1975
1976You can add more tags inside ** in your help file. But be careful not to use
1977existing help tags. You would probably use the name of your plugin in most of
1978them, like "typecorr-settings" in the example.
1979
1980Using references to other parts of the help in || is recommended. This makes
1981it easy for the user to find associated help.
1982
1983
1984FILETYPE DETECTION *plugin-filetype*
1985
1986If your filetype is not already detected by Vim, you should create a filetype
1987detection snippet in a separate file. It is usually in the form of an
1988autocommand that sets the filetype when the file name matches a pattern.
1989Example: >
1990
1991 au BufNewFile,BufRead *.foo set filetype=foofoo
1992
1993Write this single-line file as "ftdetect/foofoo.vim" in the first directory
1994that appears in 'runtimepath'. For Unix that would be
1995"~/.vim/ftdetect/foofoo.vim". The convention is to use the name of the
1996filetype for the script name.
1997
1998You can make more complicated checks if you like, for example to inspect the
1999contents of the file to recognize the language. Also see |new-filetype|.
2000
2001
2002SUMMARY *plugin-special*
2003
2004Summary of special things to use in a plugin:
2005
2006s:name Variables local to the script.
2007
2008<SID> Script-ID, used for mappings and functions local to
2009 the script.
2010
2011hasmapto() Function to test if the user already defined a mapping
2012 for functionality the script offers.
2013
2014<Leader> Value of "mapleader", which the user defines as the
2015 keys that plugin mappings start with.
2016
2017:map <unique> Give a warning if a mapping already exists.
2018
2019:noremap <script> Use only mappings local to the script, not global
2020 mappings.
2021
2022exists(":Cmd") Check if a user command already exists.
2023
2024==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00002025*41.12* Writing a filetype plugin *write-filetype-plugin* *ftplugin*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002026
2027A filetype plugin is like a global plugin, except that it sets options and
2028defines mappings for the current buffer only. See |add-filetype-plugin| for
2029how this type of plugin is used.
2030
Bram Moolenaar7c626922005-02-07 22:01:03 +00002031First read the section on global plugins above |41.11|. All that is said there
Bram Moolenaar071d4272004-06-13 20:20:40 +00002032also applies to filetype plugins. There are a few extras, which are explained
2033here. The essential thing is that a filetype plugin should only have an
2034effect on the current buffer.
2035
2036
2037DISABLING
2038
2039If you are writing a filetype plugin to be used by many people, they need a
2040chance to disable loading it. Put this at the top of the plugin: >
2041
2042 " Only do this when not done yet for this buffer
2043 if exists("b:did_ftplugin")
2044 finish
2045 endif
2046 let b:did_ftplugin = 1
2047
2048This also needs to be used to avoid that the same plugin is executed twice for
2049the same buffer (happens when using an ":edit" command without arguments).
2050
2051Now users can disable loading the default plugin completely by making a
2052filetype plugin with only this line: >
2053
2054 let b:did_ftplugin = 1
2055
2056This does require that the filetype plugin directory comes before $VIMRUNTIME
2057in 'runtimepath'!
2058
2059If you do want to use the default plugin, but overrule one of the settings,
2060you can write the different setting in a script: >
2061
2062 setlocal textwidth=70
2063
2064Now write this in the "after" directory, so that it gets sourced after the
2065distributed "vim.vim" ftplugin |after-directory|. For Unix this would be
2066"~/.vim/after/ftplugin/vim.vim". Note that the default plugin will have set
2067"b:did_ftplugin", but it is ignored here.
2068
2069
2070OPTIONS
2071
2072To make sure the filetype plugin only affects the current buffer use the >
2073
2074 :setlocal
2075
2076command to set options. And only set options which are local to a buffer (see
2077the help for the option to check that). When using |:setlocal| for global
2078options or options local to a window, the value will change for many buffers,
2079and that is not what a filetype plugin should do.
2080
2081When an option has a value that is a list of flags or items, consider using
2082"+=" and "-=" to keep the existing value. Be aware that the user may have
2083changed an option value already. First resetting to the default value and
2084then changing it often a good idea. Example: >
2085
2086 :setlocal formatoptions& formatoptions+=ro
2087
2088
2089MAPPINGS
2090
2091To make sure mappings will only work in the current buffer use the >
2092
2093 :map <buffer>
2094
2095command. This needs to be combined with the two-step mapping explained above.
2096An example of how to define functionality in a filetype plugin: >
2097
2098 if !hasmapto('<Plug>JavaImport')
2099 map <buffer> <unique> <LocalLeader>i <Plug>JavaImport
2100 endif
2101 noremap <buffer> <unique> <Plug>JavaImport oimport ""<Left><Esc>
2102
2103|hasmapto()| is used to check if the user has already defined a map to
2104<Plug>JavaImport. If not, then the filetype plugin defines the default
2105mapping. This starts with |<LocalLeader>|, which allows the user to select
2106the key(s) he wants filetype plugin mappings to start with. The default is a
2107backslash.
2108"<unique>" is used to give an error message if the mapping already exists or
2109overlaps with an existing mapping.
2110|:noremap| is used to avoid that any other mappings that the user has defined
2111interferes. You might want to use ":noremap <script>" to allow remapping
2112mappings defined in this script that start with <SID>.
2113
2114The user must have a chance to disable the mappings in a filetype plugin,
2115without disabling everything. Here is an example of how this is done for a
2116plugin for the mail filetype: >
2117
2118 " Add mappings, unless the user didn't want this.
2119 if !exists("no_plugin_maps") && !exists("no_mail_maps")
2120 " Quote text by inserting "> "
2121 if !hasmapto('<Plug>MailQuote')
2122 vmap <buffer> <LocalLeader>q <Plug>MailQuote
2123 nmap <buffer> <LocalLeader>q <Plug>MailQuote
2124 endif
2125 vnoremap <buffer> <Plug>MailQuote :s/^/> /<CR>
2126 nnoremap <buffer> <Plug>MailQuote :.,$s/^/> /<CR>
2127 endif
2128
2129Two global variables are used:
2130no_plugin_maps disables mappings for all filetype plugins
2131no_mail_maps disables mappings for a specific filetype
2132
2133
2134USER COMMANDS
2135
2136To add a user command for a specific file type, so that it can only be used in
2137one buffer, use the "-buffer" argument to |:command|. Example: >
2138
2139 :command -buffer Make make %:r.s
2140
2141
2142VARIABLES
2143
2144A filetype plugin will be sourced for each buffer of the type it's for. Local
2145script variables |s:var| will be shared between all invocations. Use local
2146buffer variables |b:var| if you want a variable specifically for one buffer.
2147
2148
2149FUNCTIONS
2150
2151When defining a function, this only needs to be done once. But the filetype
2152plugin will be sourced every time a file with this filetype will be opened.
2153This construct make sure the function is only defined once: >
2154
2155 :if !exists("*s:Func")
2156 : function s:Func(arg)
2157 : ...
2158 : endfunction
2159 :endif
2160<
2161
2162UNDO *undo_ftplugin*
2163
2164When the user does ":setfiletype xyz" the effect of the previous filetype
2165should be undone. Set the b:undo_ftplugin variable to the commands that will
2166undo the settings in your filetype plugin. Example: >
2167
2168 let b:undo_ftplugin = "setlocal fo< com< tw< commentstring<"
2169 \ . "| unlet b:match_ignorecase b:match_words b:match_skip"
2170
2171Using ":setlocal" with "<" after the option name resets the option to its
2172global value. That is mostly the best way to reset the option value.
2173
2174This does require removing the "C" flag from 'cpoptions' to allow line
2175continuation, as mentioned above |use-cpo-save|.
2176
2177
2178FILE NAME
2179
2180The filetype must be included in the file name |ftplugin-name|. Use one of
2181these three forms:
2182
2183 .../ftplugin/stuff.vim
2184 .../ftplugin/stuff_foo.vim
2185 .../ftplugin/stuff/bar.vim
2186
2187"stuff" is the filetype, "foo" and "bar" are arbitrary names.
2188
2189
2190SUMMARY *ftplugin-special*
2191
2192Summary of special things to use in a filetype plugin:
2193
2194<LocalLeader> Value of "maplocalleader", which the user defines as
2195 the keys that filetype plugin mappings start with.
2196
2197:map <buffer> Define a mapping local to the buffer.
2198
2199:noremap <script> Only remap mappings defined in this script that start
2200 with <SID>.
2201
2202:setlocal Set an option for the current buffer only.
2203
2204:command -buffer Define a user command local to the buffer.
2205
2206exists("*s:Func") Check if a function was already defined.
2207
2208Also see |plugin-special|, the special things used for all plugins.
2209
2210==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00002211*41.13* Writing a compiler plugin *write-compiler-plugin*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002212
2213A compiler plugin sets options for use with a specific compiler. The user can
2214load it with the |:compiler| command. The main use is to set the
2215'errorformat' and 'makeprg' options.
2216
2217Easiest is to have a look at examples. This command will edit all the default
2218compiler plugins: >
2219
2220 :next $VIMRUNTIME/compiler/*.vim
2221
2222Use |:next| to go to the next plugin file.
2223
2224There are two special items about these files. First is a mechanism to allow
2225a user to overrule or add to the default file. The default files start with: >
2226
2227 :if exists("current_compiler")
2228 : finish
2229 :endif
2230 :let current_compiler = "mine"
2231
2232When you write a compiler file and put it in your personal runtime directory
2233(e.g., ~/.vim/compiler for Unix), you set the "current_compiler" variable to
2234make the default file skip the settings.
Bram Moolenaarc6039d82005-12-02 00:44:04 +00002235 *:CompilerSet*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002236The second mechanism is to use ":set" for ":compiler!" and ":setlocal" for
2237":compiler". Vim defines the ":CompilerSet" user command for this. However,
2238older Vim versions don't, thus your plugin should define it then. This is an
2239example: >
2240
2241 if exists(":CompilerSet") != 2
2242 command -nargs=* CompilerSet setlocal <args>
2243 endif
2244 CompilerSet errorformat& " use the default 'errorformat'
2245 CompilerSet makeprg=nmake
2246
2247When you write a compiler plugin for the Vim distribution or for a system-wide
2248runtime directory, use the mechanism mentioned above. When
2249"current_compiler" was already set by a user plugin nothing will be done.
2250
2251When you write a compiler plugin to overrule settings from a default plugin,
2252don't check "current_compiler". This plugin is supposed to be loaded
2253last, thus it should be in a directory at the end of 'runtimepath'. For Unix
2254that could be ~/.vim/after/compiler.
2255
2256==============================================================================
Bram Moolenaar05159a02005-02-26 23:04:13 +00002257*41.14* Writing a plugin that loads quickly *write-plugin-quickload*
2258
2259A plugin may grow and become quite long. The startup delay may become
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00002260noticeable, while you hardly ever use the plugin. Then it's time for a
Bram Moolenaar05159a02005-02-26 23:04:13 +00002261quickload plugin.
2262
2263The basic idea is that the plugin is loaded twice. The first time user
2264commands and mappings are defined that offer the functionality. The second
2265time the functions that implement the functionality are defined.
2266
2267It may sound surprising that quickload means loading a script twice. What we
2268mean is that it loads quickly the first time, postponing the bulk of the
2269script to the second time, which only happens when you actually use it. When
2270you always use the functionality it actually gets slower!
2271
Bram Moolenaar76916e62006-03-21 21:23:25 +00002272Note that since Vim 7 there is an alternative: use the |autoload|
2273functionality |41.15|.
2274
Bram Moolenaar05159a02005-02-26 23:04:13 +00002275The following example shows how it's done: >
2276
2277 " Vim global plugin for demonstrating quick loading
2278 " Last Change: 2005 Feb 25
2279 " Maintainer: Bram Moolenaar <Bram@vim.org>
2280 " License: This file is placed in the public domain.
2281
2282 if !exists("s:did_load")
2283 command -nargs=* BNRead call BufNetRead(<f-args>)
2284 map <F19> :call BufNetWrite('something')<CR>
2285
2286 let s:did_load = 1
2287 exe 'au FuncUndefined BufNet* source ' . expand('<sfile>')
2288 finish
2289 endif
2290
2291 function BufNetRead(...)
2292 echo 'BufNetRead(' . string(a:000) . ')'
2293 " read functionality here
2294 endfunction
2295
2296 function BufNetWrite(...)
2297 echo 'BufNetWrite(' . string(a:000) . ')'
2298 " write functionality here
2299 endfunction
2300
2301When the script is first loaded "s:did_load" is not set. The commands between
2302the "if" and "endif" will be executed. This ends in a |:finish| command, thus
2303the rest of the script is not executed.
2304
2305The second time the script is loaded "s:did_load" exists and the commands
2306after the "endif" are executed. This defines the (possible long)
2307BufNetRead() and BufNetWrite() functions.
2308
2309If you drop this script in your plugin directory Vim will execute it on
2310startup. This is the sequence of events that happens:
2311
23121. The "BNRead" command is defined and the <F19> key is mapped when the script
2313 is sourced at startup. A |FuncUndefined| autocommand is defined. The
2314 ":finish" command causes the script to terminate early.
2315
23162. The user types the BNRead command or presses the <F19> key. The
2317 BufNetRead() or BufNetWrite() function will be called.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00002318
Bram Moolenaar05159a02005-02-26 23:04:13 +000023193. Vim can't find the function and triggers the |FuncUndefined| autocommand
2320 event. Since the pattern "BufNet*" matches the invoked function, the
2321 command "source fname" will be executed. "fname" will be equal to the name
2322 of the script, no matter where it is located, because it comes from
2323 expanding "<sfile>" (see |expand()|).
2324
23254. The script is sourced again, the "s:did_load" variable exists and the
2326 functions are defined.
2327
2328Notice that the functions that are loaded afterwards match the pattern in the
2329|FuncUndefined| autocommand. You must make sure that no other plugin defines
2330functions that match this pattern.
2331
2332==============================================================================
2333*41.15* Writing library scripts *write-library-script*
2334
2335Some functionality will be required in several places. When this becomes more
2336than a few lines you will want to put it in one script and use it from many
2337scripts. We will call that one script a library script.
2338
2339Manually loading a library script is possible, so long as you avoid loading it
2340when it's already done. You can do this with the |exists()| function.
2341Example: >
2342
2343 if !exists('*MyLibFunction')
2344 runtime library/mylibscript.vim
2345 endif
2346 call MyLibFunction(arg)
2347
2348Here you need to know that MyLibFunction() is defined in a script
2349"library/mylibscript.vim" in one of the directories in 'runtimepath'.
2350
2351To make this a bit simpler Vim offers the autoload mechanism. Then the
2352example looks like this: >
2353
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002354 call mylib#myfunction(arg)
Bram Moolenaar05159a02005-02-26 23:04:13 +00002355
2356That's a lot simpler, isn't it? Vim will recognize the function name and when
2357it's not defined search for the script "autoload/mylib.vim" in 'runtimepath'.
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002358That script must define the "mylib#myfunction()" function.
Bram Moolenaar05159a02005-02-26 23:04:13 +00002359
2360You can put many other functions in the mylib.vim script, you are free to
2361organize your functions in library scripts. But you must use function names
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00002362where the part before the '#' matches the script name. Otherwise Vim would
2363not know what script to load.
Bram Moolenaar05159a02005-02-26 23:04:13 +00002364
Bram Moolenaard1f56e62006-02-22 21:25:37 +00002365If you get really enthusiastic and write lots of library scripts, you may
Bram Moolenaar05159a02005-02-26 23:04:13 +00002366want to use subdirectories. Example: >
2367
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002368 call netlib#ftp#read('somefile')
Bram Moolenaar05159a02005-02-26 23:04:13 +00002369
2370For Unix the library script used for this could be:
2371
2372 ~/.vim/autoload/netlib/ftp.vim
2373
2374Where the function is defined like this: >
2375
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002376 function netlib#ftp#read(fname)
Bram Moolenaar05159a02005-02-26 23:04:13 +00002377 " Read the file fname through ftp
2378 endfunction
2379
2380Notice that the name the function is defined with is exactly the same as the
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00002381name used for calling the function. And the part before the last '#'
Bram Moolenaar05159a02005-02-26 23:04:13 +00002382exactly matches the subdirectory and script name.
2383
2384You can use the same mechanism for variables: >
2385
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002386 let weekdays = dutch#weekdays
Bram Moolenaar05159a02005-02-26 23:04:13 +00002387
2388This will load the script "autoload/dutch.vim", which should contain something
2389like: >
2390
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002391 let dutch#weekdays = ['zondag', 'maandag', 'dinsdag', 'woensdag',
Bram Moolenaar05159a02005-02-26 23:04:13 +00002392 \ 'donderdag', 'vrijdag', 'zaterdag']
2393
2394Further reading: |autoload|.
2395
2396==============================================================================
Bram Moolenaar76916e62006-03-21 21:23:25 +00002397*41.16* Distributing Vim scripts *distribute-script*
2398
2399Vim users will look for scripts on the Vim website: http://www.vim.org.
2400If you made something that is useful for others, share it!
2401
2402Vim scripts can be used on any system. There might not be a tar or gzip
2403command. If you want to pack files together and/or compress them the "zip"
2404utility is recommended.
2405
2406For utmost portability use Vim itself to pack scripts together. This can be
2407done with the Vimball utility. See |vimball|.
2408
Bram Moolenaarc01140a2006-03-24 22:21:52 +00002409It's good if you add a line to allow automatic updating. See |glvs-plugins|.
2410
Bram Moolenaar76916e62006-03-21 21:23:25 +00002411==============================================================================
Bram Moolenaar071d4272004-06-13 20:20:40 +00002412
2413Next chapter: |usr_42.txt| Add new menus
2414
2415Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: