blob: b58edb9c0b305797b19c537078befb512303933a [file] [log] [blame]
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +02001*usr_41.txt* For Vim version 7.4. Last change: 2016 Jul 24
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
Bram Moolenaar00654022011-02-25 14:42:19 +0100316Grouping is done with parentheses. No surprises here. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000317
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
Bram Moolenaar00654022011-02-25 14:42:19 +0100540between parentheses separated by commas. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000541
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
Bram Moolenaara3f41662010-07-11 19:01:06 +0200579String manipulation: *string-functions*
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 Moolenaar6f1d9a02016-07-24 14:12:38 +0200595 matchstrpos() match and positions of a pattern in a string
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000596 matchlist() like matchstr() and also return submatches
Bram Moolenaar071d4272004-06-13 20:20:40 +0000597 stridx() first index of a short string in a long string
598 strridx() last index of a short string in a long string
Bram Moolenaar8d043172014-01-23 14:24:41 +0100599 strlen() length of a string in bytes
600 strchars() length of a string in characters
601 strwidth() size of string when displayed
602 strdisplaywidth() size of string when displayed, deals with tabs
Bram Moolenaar071d4272004-06-13 20:20:40 +0000603 substitute() substitute a pattern match with a string
Bram Moolenaar251e1912011-06-19 05:09:16 +0200604 submatch() get a specific match in ":s" and substitute()
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200605 strpart() get part of a string using byte index
606 strcharpart() get part of a string using char index
607 strgetchar() get character from a string using char index
Bram Moolenaar071d4272004-06-13 20:20:40 +0000608 expand() expand special keywords
Bram Moolenaar071d4272004-06-13 20:20:40 +0000609 iconv() convert text from one encoding to another
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000610 byteidx() byte index of a character in a string
Bram Moolenaar8d043172014-01-23 14:24:41 +0100611 byteidxcomp() like byteidx() but count composing characters
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000612 repeat() repeat a string multiple times
613 eval() evaluate a string expression
Bram Moolenaar063b9d12016-07-09 20:21:48 +0200614 execute() execute an Ex command and get the output
Bram Moolenaar071d4272004-06-13 20:20:40 +0000615
Bram Moolenaara3f41662010-07-11 19:01:06 +0200616List manipulation: *list-functions*
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000617 get() get an item without error for wrong index
618 len() number of items in a List
619 empty() check if List is empty
620 insert() insert an item somewhere in a List
621 add() append an item to a List
622 extend() append a List to a List
623 remove() remove one or more items from a List
624 copy() make a shallow copy of a List
625 deepcopy() make a full copy of a List
626 filter() remove selected items from a List
627 map() change each List item
628 sort() sort a List
629 reverse() reverse the order of a List
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +0100630 uniq() remove copies of repeated adjacent items
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000631 split() split a String into a List
632 join() join List items into a String
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000633 range() return a List with a sequence of numbers
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000634 string() String representation of a List
635 call() call a function with List as arguments
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000636 index() index of a value in a List
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000637 max() maximum value in a List
638 min() minimum value in a List
639 count() count number of times a value appears in a List
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000640 repeat() repeat a List multiple times
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000641
Bram Moolenaara3f41662010-07-11 19:01:06 +0200642Dictionary manipulation: *dict-functions*
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000643 get() get an entry without an error for a wrong key
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000644 len() number of entries in a Dictionary
645 has_key() check whether a key appears in a Dictionary
646 empty() check if Dictionary is empty
647 remove() remove an entry from a Dictionary
648 extend() add entries from one Dictionary to another
649 filter() remove selected entries from a Dictionary
650 map() change each Dictionary entry
651 keys() get List of Dictionary keys
652 values() get List of Dictionary values
653 items() get List of Dictionary key-value pairs
654 copy() make a shallow copy of a Dictionary
655 deepcopy() make a full copy of a Dictionary
656 string() String representation of a Dictionary
657 max() maximum value in a Dictionary
658 min() minimum value in a Dictionary
659 count() count number of times a value appears
660
Bram Moolenaara3f41662010-07-11 19:01:06 +0200661Floating point computation: *float-functions*
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000662 float2nr() convert Float to Number
663 abs() absolute value (also works for Number)
664 round() round off
665 ceil() round up
666 floor() round down
667 trunc() remove value after decimal point
Bram Moolenaar8d043172014-01-23 14:24:41 +0100668 fmod() remainder of division
669 exp() exponential
670 log() natural logarithm (logarithm to base e)
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000671 log10() logarithm to base 10
672 pow() value of x to the exponent y
673 sqrt() square root
674 sin() sine
675 cos() cosine
Bram Moolenaar662db672011-03-22 14:05:35 +0100676 tan() tangent
677 asin() arc sine
678 acos() arc cosine
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000679 atan() arc tangent
Bram Moolenaar662db672011-03-22 14:05:35 +0100680 atan2() arc tangent
681 sinh() hyperbolic sine
682 cosh() hyperbolic cosine
683 tanh() hyperbolic tangent
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200684 isnan() check for not a number
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000685
Bram Moolenaarb6b046b2011-12-30 13:11:27 +0100686Other computation: *bitwise-function*
687 and() bitwise AND
688 invert() bitwise invert
689 or() bitwise OR
690 xor() bitwise XOR
Bram Moolenaar8d043172014-01-23 14:24:41 +0100691 sha256() SHA-256 hash
Bram Moolenaarb6b046b2011-12-30 13:11:27 +0100692
Bram Moolenaara3f41662010-07-11 19:01:06 +0200693Variables: *var-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000694 type() type of a variable
695 islocked() check if a variable is locked
696 function() get a Funcref for a function name
697 getbufvar() get a variable value from a specific buffer
698 setbufvar() set a variable in a specific buffer
Bram Moolenaarc6249bb2006-04-15 20:25:09 +0000699 getwinvar() get a variable from specific window
Bram Moolenaar06b5d512010-05-22 15:37:44 +0200700 gettabvar() get a variable from specific tab page
Bram Moolenaarc6249bb2006-04-15 20:25:09 +0000701 gettabwinvar() get a variable from specific window & tab page
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000702 setwinvar() set a variable in a specific window
Bram Moolenaar06b5d512010-05-22 15:37:44 +0200703 settabvar() set a variable in a specific tab page
Bram Moolenaarc6249bb2006-04-15 20:25:09 +0000704 settabwinvar() set a variable in a specific window & tab page
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000705 garbagecollect() possibly free memory
706
Bram Moolenaara3f41662010-07-11 19:01:06 +0200707Cursor and mark position: *cursor-functions* *mark-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000708 col() column number of the cursor or a mark
709 virtcol() screen column of the cursor or a mark
710 line() line number of the cursor or mark
711 wincol() window column number of the cursor
712 winline() window line number of the cursor
713 cursor() position the cursor at a line/column
Bram Moolenaar8d043172014-01-23 14:24:41 +0100714 screencol() get screen column of the cursor
715 screenrow() get screen row of the cursor
Bram Moolenaar822ff862014-06-12 21:46:14 +0200716 getcurpos() get position of the cursor
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000717 getpos() get position of cursor, mark, etc.
718 setpos() set position of cursor, mark, etc.
719 byte2line() get line number at a specific byte count
720 line2byte() byte count at a specific line
721 diff_filler() get the number of filler lines above a line
Bram Moolenaar8d043172014-01-23 14:24:41 +0100722 screenattr() get attribute at a screen line/row
723 screenchar() get character code at a screen line/row
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000724
Bram Moolenaara3f41662010-07-11 19:01:06 +0200725Working with text in the current buffer: *text-functions*
Bram Moolenaar7c626922005-02-07 22:01:03 +0000726 getline() get a line or list of lines from the buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +0000727 setline() replace a line in the buffer
Bram Moolenaar7c626922005-02-07 22:01:03 +0000728 append() append line or list of lines in the buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +0000729 indent() indent of a specific line
730 cindent() indent according to C indenting
731 lispindent() indent according to Lisp indenting
732 nextnonblank() find next non-blank line
733 prevnonblank() find previous non-blank line
734 search() find a match for a pattern
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000735 searchpos() find a match for a pattern
Bram Moolenaar071d4272004-06-13 20:20:40 +0000736 searchpair() find the other end of a start/skip/end
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000737 searchpairpos() find the other end of a start/skip/end
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000738 searchdecl() search for the declaration of a name
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200739 getcharsearch() return character search information
740 setcharsearch() set character search information
Bram Moolenaar071d4272004-06-13 20:20:40 +0000741
Bram Moolenaara3f41662010-07-11 19:01:06 +0200742 *system-functions* *file-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000743System functions and manipulation of files:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000744 glob() expand wildcards
745 globpath() expand wildcards in a number of directories
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200746 glob2regpat() convert a glob pattern into a search pattern
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000747 findfile() find a file in a list of directories
748 finddir() find a directory in a list of directories
Bram Moolenaar071d4272004-06-13 20:20:40 +0000749 resolve() find out where a shortcut points to
750 fnamemodify() modify a file name
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000751 pathshorten() shorten directory names in a path
752 simplify() simplify a path without changing its meaning
Bram Moolenaar071d4272004-06-13 20:20:40 +0000753 executable() check if an executable program exists
Bram Moolenaar7e38ea22014-04-05 22:55:53 +0200754 exepath() full path of an executable program
Bram Moolenaar071d4272004-06-13 20:20:40 +0000755 filereadable() check if a file can be read
756 filewritable() check if a file can be written to
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000757 getfperm() get the permissions of a file
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200758 setfperm() set the permissions of a file
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000759 getftype() get the kind of a file
Bram Moolenaar071d4272004-06-13 20:20:40 +0000760 isdirectory() check if a directory exists
Bram Moolenaar071d4272004-06-13 20:20:40 +0000761 getfsize() get the size of a file
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000762 getcwd() get the current working directory
Bram Moolenaard267b9c2007-04-26 15:06:45 +0000763 haslocaldir() check if current window used |:lcd|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000764 tempname() get the name of a temporary file
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000765 mkdir() create a new directory
Bram Moolenaar071d4272004-06-13 20:20:40 +0000766 delete() delete a file
767 rename() rename a file
Bram Moolenaar7e38ea22014-04-05 22:55:53 +0200768 system() get the result of a shell command as a string
769 systemlist() get the result of a shell command as a list
Bram Moolenaar071d4272004-06-13 20:20:40 +0000770 hostname() name of the system
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +0000771 readfile() read a file into a List of lines
772 writefile() write a List of lines into a file
Bram Moolenaar071d4272004-06-13 20:20:40 +0000773
Bram Moolenaara3f41662010-07-11 19:01:06 +0200774Date and Time: *date-functions* *time-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000775 getftime() get last modification time of a file
776 localtime() get current time in seconds
777 strftime() convert time to a string
778 reltime() get the current or elapsed time accurately
779 reltimestr() convert reltime() result to a string
Bram Moolenaar03413f42016-04-12 21:07:15 +0200780 reltimefloat() convert reltime() result to a Float
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000781
Bram Moolenaara3f41662010-07-11 19:01:06 +0200782 *buffer-functions* *window-functions* *arg-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000783Buffers, windows and the argument list:
784 argc() number of entries in the argument list
785 argidx() current position in the argument list
Bram Moolenaar2d1fe052014-05-28 18:22:57 +0200786 arglistid() get id of the argument list
Bram Moolenaar071d4272004-06-13 20:20:40 +0000787 argv() get one entry from the argument list
788 bufexists() check if a buffer exists
789 buflisted() check if a buffer exists and is listed
790 bufloaded() check if a buffer exists and is loaded
791 bufname() get the name of a specific buffer
792 bufnr() get the buffer number of a specific buffer
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000793 tabpagebuflist() return List of buffers in a tab page
794 tabpagenr() get the number of a tab page
795 tabpagewinnr() like winnr() for a specified tab page
Bram Moolenaar071d4272004-06-13 20:20:40 +0000796 winnr() get the window number for the current window
Bram Moolenaar82af8712016-06-04 20:20:29 +0200797 bufwinid() get the window ID of a specific buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +0000798 bufwinnr() get the window number of a specific buffer
799 winbufnr() get the buffer number of a specific window
Bram Moolenaara3ffd9c2005-07-21 21:03:15 +0000800 getbufline() get a list of lines from the specified buffer
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200801 win_findbuf() find windows containing a buffer
802 win_getid() get window ID of a window
803 win_gotoid() go to window with ID
804 win_id2tabwin() get tab and window nr from window ID
805 win_id2win() get window nr from window ID
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000806
Bram Moolenaara3f41662010-07-11 19:01:06 +0200807Command line: *command-line-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000808 getcmdline() get the current command line
809 getcmdpos() get position of the cursor in the command line
810 setcmdpos() set position of the cursor in the command line
811 getcmdtype() return the current command-line type
Bram Moolenaarfb539272014-08-22 19:21:47 +0200812 getcmdwintype() return the current command-line window type
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +0200813 getcompletion() list of command-line completion matches
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000814
Bram Moolenaara3f41662010-07-11 19:01:06 +0200815Quickfix and location lists: *quickfix-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000816 getqflist() list of quickfix errors
817 setqflist() modify a quickfix list
818 getloclist() list of location list items
819 setloclist() modify a location list
820
Bram Moolenaara3f41662010-07-11 19:01:06 +0200821Insert mode completion: *completion-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000822 complete() set found matches
823 complete_add() add to found matches
824 complete_check() check if completion should be aborted
825 pumvisible() check if the popup menu is displayed
Bram Moolenaar071d4272004-06-13 20:20:40 +0000826
Bram Moolenaara3f41662010-07-11 19:01:06 +0200827Folding: *folding-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000828 foldclosed() check for a closed fold at a specific line
829 foldclosedend() like foldclosed() but return the last line
830 foldlevel() check for the fold level at a specific line
831 foldtext() generate the line displayed for a closed fold
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000832 foldtextresult() get the text displayed for a closed fold
Bram Moolenaar071d4272004-06-13 20:20:40 +0000833
Bram Moolenaara3f41662010-07-11 19:01:06 +0200834Syntax and highlighting: *syntax-functions* *highlighting-functions*
Bram Moolenaar6ee10162007-07-26 20:58:42 +0000835 clearmatches() clear all matches defined by |matchadd()| and
836 the |:match| commands
837 getmatches() get all matches defined by |matchadd()| and
838 the |:match| commands
Bram Moolenaar071d4272004-06-13 20:20:40 +0000839 hlexists() check if a highlight group exists
840 hlID() get ID of a highlight group
841 synID() get syntax ID at a specific position
842 synIDattr() get a specific attribute of a syntax ID
843 synIDtrans() get translated syntax ID
Bram Moolenaar166af9b2010-11-16 20:34:40 +0100844 synstack() get list of syntax IDs at a specific position
Bram Moolenaar81af9252010-12-10 20:35:50 +0100845 synconcealed() get info about concealing
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000846 diff_hlID() get highlight ID for diff mode at a position
Bram Moolenaar6ee10162007-07-26 20:58:42 +0000847 matchadd() define a pattern to highlight (a "match")
Bram Moolenaarb3414592014-06-17 17:48:32 +0200848 matchaddpos() define a list of positions to highlight
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000849 matcharg() get info about |:match| arguments
Bram Moolenaar6ee10162007-07-26 20:58:42 +0000850 matchdelete() delete a match defined by |matchadd()| or a
851 |:match| command
852 setmatches() restore a list of matches saved by
853 |getmatches()|
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000854
Bram Moolenaara3f41662010-07-11 19:01:06 +0200855Spelling: *spell-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000856 spellbadword() locate badly spelled word at or after cursor
857 spellsuggest() return suggested spelling corrections
858 soundfold() return the sound-a-like equivalent of a word
Bram Moolenaar071d4272004-06-13 20:20:40 +0000859
Bram Moolenaara3f41662010-07-11 19:01:06 +0200860History: *history-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000861 histadd() add an item to a history
862 histdel() delete an item from a history
863 histget() get an item from a history
864 histnr() get highest index of a history list
865
Bram Moolenaara3f41662010-07-11 19:01:06 +0200866Interactive: *interactive-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000867 browse() put up a file requester
868 browsedir() put up a directory requester
Bram Moolenaar071d4272004-06-13 20:20:40 +0000869 confirm() let the user make a choice
870 getchar() get a character from the user
871 getcharmod() get modifiers for the last typed character
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000872 feedkeys() put characters in the typeahead queue
Bram Moolenaar071d4272004-06-13 20:20:40 +0000873 input() get a line from the user
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000874 inputlist() let the user pick an entry from a list
Bram Moolenaar071d4272004-06-13 20:20:40 +0000875 inputsecret() get a line from the user without showing it
876 inputdialog() get a line from the user in a dialog
Bram Moolenaar68b76a62005-03-25 21:53:48 +0000877 inputsave() save and clear typeahead
Bram Moolenaar071d4272004-06-13 20:20:40 +0000878 inputrestore() restore typeahead
879
Bram Moolenaara3f41662010-07-11 19:01:06 +0200880GUI: *gui-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000881 getfontname() get name of current font being used
882 getwinposx() X position of the GUI Vim window
883 getwinposy() Y position of the GUI Vim window
884
Bram Moolenaara3f41662010-07-11 19:01:06 +0200885Vim server: *server-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000886 serverlist() return the list of server names
887 remote_send() send command characters to a Vim server
888 remote_expr() evaluate an expression in a Vim server
889 server2client() send a reply to a client of a Vim server
890 remote_peek() check if there is a reply from a Vim server
891 remote_read() read a reply from a Vim server
892 foreground() move the Vim window to the foreground
893 remote_foreground() move the Vim server window to the foreground
894
Bram Moolenaara3f41662010-07-11 19:01:06 +0200895Window size and position: *window-size-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000896 winheight() get height of a specific window
897 winwidth() get width of a specific window
898 winrestcmd() return command to restore window sizes
899 winsaveview() get view of current window
900 winrestview() restore saved view of current window
901
Bram Moolenaar26402cb2013-02-20 21:26:00 +0100902Mappings: *mapping-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000903 hasmapto() check if a mapping exists
904 mapcheck() check if a matching mapping exists
905 maparg() get rhs of a mapping
Bram Moolenaar26402cb2013-02-20 21:26:00 +0100906 wildmenumode() check if the wildmode is active
907
Bram Moolenaar683fa182015-11-30 21:38:24 +0100908Testing: *test-functions*
Bram Moolenaare18c0b32016-03-20 21:08:34 +0100909 assert_equal() assert that two expressions values are equal
Bram Moolenaar03413f42016-04-12 21:07:15 +0200910 assert_notequal() assert that two expressions values are not equal
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +0200911 assert_inrange() assert that an expression is inside a range
Bram Moolenaar7db8f6f2016-03-29 23:12:46 +0200912 assert_match() assert that a pattern matches the value
Bram Moolenaar03413f42016-04-12 21:07:15 +0200913 assert_notmatch() assert that a pattern does not match the value
Bram Moolenaar683fa182015-11-30 21:38:24 +0100914 assert_false() assert that an expression is false
915 assert_true() assert that an expression is true
Bram Moolenaare18c0b32016-03-20 21:08:34 +0100916 assert_exception() assert that a command throws an exception
917 assert_fails() assert that a function call fails
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200918 test_alloc_fail() make memory allocation fail
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +0200919 test_autochdir() enable 'autochdir' during startup
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200920 test_disable_char_avail() test without typeahead
921 test_garbagecollect_now() free memory right now
922 test_null_channel() return a null Channel
923 test_null_dict() return a null Dict
924 test_null_job() return a null Job
925 test_null_list() return a null List
926 test_null_partial() return a null Partial function
927 test_null_string() return a null String
Bram Moolenaar683fa182015-11-30 21:38:24 +0100928
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200929Inter-process communication: *channel-functions*
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100930 ch_open() open a channel
931 ch_close() close a channel
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200932 ch_read() read a message from a channel
933 ch_readraw() read a raw message from a channel
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100934 ch_sendexpr() send a JSON message over a channel
935 ch_sendraw() send a raw message over a channel
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200936 ch_evalexpr() evaluates an expression over channel
937 ch_evalraw() evaluates a raw string over channel
938 ch_status() get status of a channel
939 ch_getbufnr() get the buffer number of a channel
940 ch_getjob() get the job associated with a channel
941 ch_info() get channel information
942 ch_log() write a message in the channel log file
943 ch_logfile() set the channel log file
944 ch_setoptions() set the options for a channel
Bram Moolenaara02a5512016-06-17 12:48:11 +0200945 json_encode() encode an expression to a JSON string
946 json_decode() decode a JSON string to Vim types
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200947 js_encode() encode an expression to a JSON string
948 js_decode() decode a JSON string to Vim types
949
950Jobs: *job-functions*
951 job_start() start a job
952 job_stop() stop a job
953 job_status() get the status of a job
954 job_getchannel() get the channel used by a job
955 job_info() get information about a job
956 job_setoptions() set options for a job
957
958Timers: *timer-functions*
959 timer_start() create a timer
960 timer_stop() stop a timer
Bram Moolenaar298b4402016-01-28 22:38:53 +0100961
Bram Moolenaar26402cb2013-02-20 21:26:00 +0100962Various: *various-functions*
963 mode() get current editing mode
964 visualmode() last visual mode used
Bram Moolenaar071d4272004-06-13 20:20:40 +0000965 exists() check if a variable, function, etc. exists
966 has() check if a feature is supported in Vim
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000967 changenr() return number of most recent change
Bram Moolenaar071d4272004-06-13 20:20:40 +0000968 cscope_connection() check if a cscope connection exists
969 did_filetype() check if a FileType autocommand was used
970 eventhandler() check if invoked by an event handler
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000971 getpid() get process ID of Vim
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000972
Bram Moolenaar071d4272004-06-13 20:20:40 +0000973 libcall() call a function in an external library
974 libcallnr() idem, returning a number
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000975
Bram Moolenaar8d043172014-01-23 14:24:41 +0100976 undofile() get the name of the undo file
977 undotree() return the state of the undo tree
978
Bram Moolenaar071d4272004-06-13 20:20:40 +0000979 getreg() get contents of a register
980 getregtype() get type of a register
981 setreg() set contents and type of a register
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000982
Bram Moolenaar8d043172014-01-23 14:24:41 +0100983 shiftwidth() effective value of 'shiftwidth'
984
Bram Moolenaar063b9d12016-07-09 20:21:48 +0200985 wordcount() get byte/word/char count of buffer
986
Bram Moolenaarda5d7402005-03-16 09:50:44 +0000987 taglist() get list of matching tags
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000988 tagfiles() get a list of tags files
Bram Moolenaar071d4272004-06-13 20:20:40 +0000989
Bram Moolenaar8d043172014-01-23 14:24:41 +0100990 luaeval() evaluate Lua expression
Bram Moolenaar7e506b62010-01-19 15:55:06 +0100991 mzeval() evaluate |MzScheme| expression
Bram Moolenaare9b892e2016-01-17 21:15:58 +0100992 perleval() evaluate Perl expression (|+perl|)
Bram Moolenaar8d043172014-01-23 14:24:41 +0100993 py3eval() evaluate Python expression (|+python3|)
994 pyeval() evaluate Python expression (|+python|)
Bram Moolenaar7e506b62010-01-19 15:55:06 +0100995
Bram Moolenaar071d4272004-06-13 20:20:40 +0000996==============================================================================
997*41.7* Defining a function
998
999Vim enables you to define your own functions. The basic function declaration
1000begins as follows: >
1001
1002 :function {name}({var1}, {var2}, ...)
1003 : {body}
1004 :endfunction
1005<
1006 Note:
1007 Function names must begin with a capital letter.
1008
1009Let's define a short function to return the smaller of two numbers. It starts
1010with this line: >
1011
1012 :function Min(num1, num2)
1013
1014This tells Vim that the function is named "Min" and it takes two arguments:
1015"num1" and "num2".
1016 The first thing you need to do is to check to see which number is smaller:
1017 >
1018 : if a:num1 < a:num2
1019
1020The special prefix "a:" tells Vim that the variable is a function argument.
1021Let's assign the variable "smaller" the value of the smallest number: >
1022
1023 : if a:num1 < a:num2
1024 : let smaller = a:num1
1025 : else
1026 : let smaller = a:num2
1027 : endif
1028
1029The variable "smaller" is a local variable. Variables used inside a function
1030are local unless prefixed by something like "g:", "a:", or "s:".
1031
1032 Note:
1033 To access a global variable from inside a function you must prepend
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00001034 "g:" to it. Thus "g:today" inside a function is used for the global
1035 variable "today", and "today" is another variable, local to the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001036 function.
1037
1038You now use the ":return" statement to return the smallest number to the user.
1039Finally, you end the function: >
1040
1041 : return smaller
1042 :endfunction
1043
1044The complete function definition is as follows: >
1045
1046 :function Min(num1, num2)
1047 : if a:num1 < a:num2
1048 : let smaller = a:num1
1049 : else
1050 : let smaller = a:num2
1051 : endif
1052 : return smaller
1053 :endfunction
1054
Bram Moolenaar7c626922005-02-07 22:01:03 +00001055For people who like short functions, this does the same thing: >
1056
1057 :function Min(num1, num2)
1058 : if a:num1 < a:num2
1059 : return a:num1
1060 : endif
1061 : return a:num2
1062 :endfunction
1063
Bram Moolenaard1f56e62006-02-22 21:25:37 +00001064A user defined function is called in exactly the same way as a built-in
Bram Moolenaar071d4272004-06-13 20:20:40 +00001065function. Only the name is different. The Min function can be used like
1066this: >
1067
1068 :echo Min(5, 8)
1069
1070Only now will the function be executed and the lines be interpreted by Vim.
1071If there are mistakes, like using an undefined variable or function, you will
1072now get an error message. When defining the function these errors are not
1073detected.
1074
1075When a function reaches ":endfunction" or ":return" is used without an
1076argument, the function returns zero.
1077
1078To redefine a function that already exists, use the ! for the ":function"
1079command: >
1080
1081 :function! Min(num1, num2, num3)
1082
1083
1084USING A RANGE
1085
1086The ":call" command can be given a line range. This can have one of two
1087meanings. When a function has been defined with the "range" keyword, it will
1088take care of the line range itself.
1089 The function will be passed the variables "a:firstline" and "a:lastline".
1090These will have the line numbers from the range the function was called with.
1091Example: >
1092
1093 :function Count_words() range
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00001094 : let lnum = a:firstline
1095 : let n = 0
1096 : while lnum <= a:lastline
1097 : let n = n + len(split(getline(lnum)))
1098 : let lnum = lnum + 1
Bram Moolenaar071d4272004-06-13 20:20:40 +00001099 : endwhile
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00001100 : echo "found " . n . " words"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001101 :endfunction
1102
1103You can call this function with: >
1104
1105 :10,30call Count_words()
1106
1107It will be executed once and echo the number of words.
1108 The other way to use a line range is by defining a function without the
1109"range" keyword. The function will be called once for every line in the
1110range, with the cursor in that line. Example: >
1111
1112 :function Number()
1113 : echo "line " . line(".") . " contains: " . getline(".")
1114 :endfunction
1115
1116If you call this function with: >
1117
1118 :10,15call Number()
1119
1120The function will be called six times.
1121
1122
1123VARIABLE NUMBER OF ARGUMENTS
1124
1125Vim enables you to define functions that have a variable number of arguments.
1126The following command, for instance, defines a function that must have 1
1127argument (start) and can have up to 20 additional arguments: >
1128
1129 :function Show(start, ...)
1130
1131The variable "a:1" contains the first optional argument, "a:2" the second, and
1132so on. The variable "a:0" contains the number of extra arguments.
1133 For example: >
1134
1135 :function Show(start, ...)
1136 : echohl Title
Bram Moolenaar00654022011-02-25 14:42:19 +01001137 : echo "start is " . a:start
Bram Moolenaar071d4272004-06-13 20:20:40 +00001138 : echohl None
1139 : let index = 1
1140 : while index <= a:0
1141 : echo " Arg " . index . " is " . a:{index}
1142 : let index = index + 1
1143 : endwhile
1144 : echo ""
1145 :endfunction
1146
1147This uses the ":echohl" command to specify the highlighting used for the
1148following ":echo" command. ":echohl None" stops it again. The ":echon"
1149command works like ":echo", but doesn't output a line break.
1150
Bram Moolenaar7c626922005-02-07 22:01:03 +00001151You can also use the a:000 variable, it is a List of all the "..." arguments.
1152See |a:000|.
1153
Bram Moolenaar071d4272004-06-13 20:20:40 +00001154
1155LISTING FUNCTIONS
1156
1157The ":function" command lists the names and arguments of all user-defined
1158functions: >
1159
1160 :function
1161< function Show(start, ...) ~
1162 function GetVimIndent() ~
1163 function SetSyn(name) ~
1164
1165To see what a function does, use its name as an argument for ":function": >
1166
1167 :function SetSyn
1168< 1 if &syntax == '' ~
1169 2 let &syntax = a:name ~
1170 3 endif ~
1171 endfunction ~
1172
1173
1174DEBUGGING
1175
1176The line number is useful for when you get an error message or when debugging.
1177See |debug-scripts| about debugging mode.
1178 You can also set the 'verbose' option to 12 or higher to see all function
1179calls. Set it to 15 or higher to see every executed line.
1180
1181
1182DELETING A FUNCTION
1183
1184To delete the Show() function: >
1185
1186 :delfunction Show
1187
1188You get an error when the function doesn't exist.
1189
Bram Moolenaar7c626922005-02-07 22:01:03 +00001190
1191FUNCTION REFERENCES
1192
1193Sometimes it can be useful to have a variable point to one function or
1194another. You can do it with the function() function. It turns the name of a
1195function into a reference: >
1196
1197 :let result = 0 " or 1
1198 :function! Right()
1199 : return 'Right!'
1200 :endfunc
1201 :function! Wrong()
1202 : return 'Wrong!'
1203 :endfunc
1204 :
1205 :if result == 1
1206 : let Afunc = function('Right')
1207 :else
1208 : let Afunc = function('Wrong')
1209 :endif
1210 :echo call(Afunc, [])
1211< Wrong! ~
1212
1213Note that the name of a variable that holds a function reference must start
1214with a capital. Otherwise it could be confused with the name of a builtin
1215function.
1216 The way to invoke a function that a variable refers to is with the call()
1217function. Its first argument is the function reference, the second argument
1218is a List with arguments.
1219
1220Function references are most useful in combination with a Dictionary, as is
1221explained in the next section.
1222
Bram Moolenaar071d4272004-06-13 20:20:40 +00001223==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00001224*41.8* Lists and Dictionaries
1225
1226So far we have used the basic types String and Number. Vim also supports two
1227composite types: List and Dictionary.
1228
1229A List is an ordered sequence of things. The things can be any kind of value,
1230thus you can make a List of numbers, a List of Lists and even a List of mixed
1231items. To create a List with three strings: >
1232
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001233 :let alist = ['aap', 'mies', 'noot']
Bram Moolenaar7c626922005-02-07 22:01:03 +00001234
1235The List items are enclosed in square brackets and separated by commas. To
1236create an empty List: >
1237
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001238 :let alist = []
Bram Moolenaar7c626922005-02-07 22:01:03 +00001239
1240You can add items to a List with the add() function: >
1241
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001242 :let alist = []
Bram Moolenaar7c626922005-02-07 22:01:03 +00001243 :call add(alist, 'foo')
1244 :call add(alist, 'bar')
1245 :echo alist
1246< ['foo', 'bar'] ~
1247
1248List concatenation is done with +: >
1249
1250 :echo alist + ['foo', 'bar']
1251< ['foo', 'bar', 'foo', 'bar'] ~
1252
1253Or, if you want to extend a List directly: >
1254
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001255 :let alist = ['one']
Bram Moolenaar7c626922005-02-07 22:01:03 +00001256 :call extend(alist, ['two', 'three'])
1257 :echo alist
1258< ['one', 'two', 'three'] ~
1259
1260Notice that using add() will have a different effect: >
1261
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001262 :let alist = ['one']
Bram Moolenaar7c626922005-02-07 22:01:03 +00001263 :call add(alist, ['two', 'three'])
1264 :echo alist
1265< ['one', ['two', 'three']] ~
1266
1267The second argument of add() is added as a single item.
1268
1269
1270FOR LOOP
1271
1272One of the nice things you can do with a List is iterate over it: >
1273
1274 :let alist = ['one', 'two', 'three']
1275 :for n in alist
1276 : echo n
1277 :endfor
1278< one ~
1279 two ~
1280 three ~
1281
1282This will loop over each element in List "alist", assigning the value to
1283variable "n". The generic form of a for loop is: >
1284
1285 :for {varname} in {listexpression}
1286 : {commands}
1287 :endfor
1288
1289To loop a certain number of times you need a List of a specific length. The
1290range() function creates one for you: >
1291
1292 :for a in range(3)
1293 : echo a
1294 :endfor
1295< 0 ~
1296 1 ~
1297 2 ~
1298
1299Notice that the first item of the List that range() produces is zero, thus the
1300last item is one less than the length of the list.
1301 You can also specify the maximum value, the stride and even go backwards: >
1302
1303 :for a in range(8, 4, -2)
1304 : echo a
1305 :endfor
1306< 8 ~
1307 6 ~
1308 4 ~
1309
1310A more useful example, looping over lines in the buffer: >
1311
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001312 :for line in getline(1, 20)
1313 : if line =~ "Date: "
1314 : echo matchstr(line, 'Date: \zs.*')
1315 : endif
1316 :endfor
Bram Moolenaar7c626922005-02-07 22:01:03 +00001317
1318This looks into lines 1 to 20 (inclusive) and echoes any date found in there.
1319
1320
1321DICTIONARIES
1322
1323A Dictionary stores key-value pairs. You can quickly lookup a value if you
1324know the key. A Dictionary is created with curly braces: >
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001325
Bram Moolenaar7c626922005-02-07 22:01:03 +00001326 :let uk2nl = {'one': 'een', 'two': 'twee', 'three': 'drie'}
1327
Bram Moolenaar4399ef42005-02-12 14:29:27 +00001328Now you can lookup words by putting the key in square brackets: >
Bram Moolenaar7c626922005-02-07 22:01:03 +00001329
1330 :echo uk2nl['two']
1331< twee ~
1332
1333The generic form for defining a Dictionary is: >
1334
1335 {<key> : <value>, ...}
1336
1337An empty Dictionary is one without any keys: >
1338
1339 {}
1340
1341The possibilities with Dictionaries are numerous. There are various functions
1342for them as well. For example, you can obtain a list of the keys and loop
1343over them: >
1344
1345 :for key in keys(uk2nl)
1346 : echo key
1347 :endfor
1348< three ~
1349 one ~
1350 two ~
1351
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00001352You will notice the keys are not ordered. You can sort the list to get a
Bram Moolenaar7c626922005-02-07 22:01:03 +00001353specific order: >
1354
1355 :for key in sort(keys(uk2nl))
1356 : echo key
1357 :endfor
1358< one ~
1359 three ~
1360 two ~
1361
1362But you can never get back the order in which items are defined. For that you
1363need to use a List, it stores items in an ordered sequence.
1364
1365
1366DICTIONARY FUNCTIONS
1367
1368The items in a Dictionary can normally be obtained with an index in square
1369brackets: >
1370
1371 :echo uk2nl['one']
1372< een ~
1373
1374A method that does the same, but without so many punctuation characters: >
1375
1376 :echo uk2nl.one
1377< een ~
1378
1379This only works for a key that is made of ASCII letters, digits and the
1380underscore. You can also assign a new value this way: >
1381
1382 :let uk2nl.four = 'vier'
1383 :echo uk2nl
1384< {'three': 'drie', 'four': 'vier', 'one': 'een', 'two': 'twee'} ~
1385
1386And now for something special: you can directly define a function and store a
1387reference to it in the dictionary: >
1388
1389 :function uk2nl.translate(line) dict
1390 : return join(map(split(a:line), 'get(self, v:val, "???")'))
1391 :endfunction
1392
1393Let's first try it out: >
1394
1395 :echo uk2nl.translate('three two five one')
1396< drie twee ??? een ~
1397
1398The first special thing you notice is the "dict" at the end of the ":function"
1399line. This marks the function as being used from a Dictionary. The "self"
1400local variable will then refer to that Dictionary.
1401 Now let's break up the complicated return command: >
1402
1403 split(a:line)
1404
Bram Moolenaar00654022011-02-25 14:42:19 +01001405The split() function takes a string, chops it into whitespace separated words
Bram Moolenaar7c626922005-02-07 22:01:03 +00001406and returns a list with these words. Thus in the example it returns: >
1407
1408 :echo split('three two five one')
1409< ['three', 'two', 'five', 'one'] ~
1410
1411This list is the first argument to the map() function. This will go through
1412the list, evaluating its second argument with "v:val" set to the value of each
1413item. This is a shortcut to using a for loop. This command: >
1414
1415 :let alist = map(split(a:line), 'get(self, v:val, "???")')
1416
1417Is equivalent to: >
1418
1419 :let alist = split(a:line)
1420 :for idx in range(len(alist))
1421 : let alist[idx] = get(self, alist[idx], "???")
1422 :endfor
1423
1424The get() function checks if a key is present in a Dictionary. If it is, then
1425the value is retrieved. If it isn't, then the default value is returned, in
Bram Moolenaar4399ef42005-02-12 14:29:27 +00001426the example it's '???'. This is a convenient way to handle situations where a
Bram Moolenaar7c626922005-02-07 22:01:03 +00001427key may not be present and you don't want an error message.
1428
1429The join() function does the opposite of split(): it joins together a list of
1430words, putting a space in between.
1431 This combination of split(), map() and join() is a nice way to filter a line
1432of words in a very compact way.
1433
1434
1435OBJECT ORIENTED PROGRAMMING
1436
1437Now that you can put both values and functions in a Dictionary, you can
1438actually use a Dictionary like an object.
1439 Above we used a Dictionary for translating Dutch to English. We might want
1440to do the same for other languages. Let's first make an object (aka
1441Dictionary) that has the translate function, but no words to translate: >
1442
1443 :let transdict = {}
1444 :function transdict.translate(line) dict
1445 : return join(map(split(a:line), 'get(self.words, v:val, "???")'))
1446 :endfunction
1447
1448It's slightly different from the function above, using 'self.words' to lookup
1449word translations. But we don't have a self.words. Thus you could call this
1450an abstract class.
1451
1452Now we can instantiate a Dutch translation object: >
1453
1454 :let uk2nl = copy(transdict)
1455 :let uk2nl.words = {'one': 'een', 'two': 'twee', 'three': 'drie'}
1456 :echo uk2nl.translate('three one')
1457< drie een ~
1458
1459And a German translator: >
1460
1461 :let uk2de = copy(transdict)
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001462 :let uk2de.words = {'one': 'eins', 'two': 'zwei', 'three': 'drei'}
Bram Moolenaar7c626922005-02-07 22:01:03 +00001463 :echo uk2de.translate('three one')
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001464< drei eins ~
Bram Moolenaar7c626922005-02-07 22:01:03 +00001465
1466You see that the copy() function is used to make a copy of the "transdict"
1467Dictionary and then the copy is changed to add the words. The original
1468remains the same, of course.
1469
1470Now you can go one step further, and use your preferred translator: >
1471
1472 :if $LANG =~ "de"
1473 : let trans = uk2de
1474 :else
1475 : let trans = uk2nl
1476 :endif
1477 :echo trans.translate('one two three')
1478< een twee drie ~
1479
1480Here "trans" refers to one of the two objects (Dictionaries). No copy is
1481made. More about List and Dictionary identity can be found at |list-identity|
1482and |dict-identity|.
1483
1484Now you might use a language that isn't supported. You can overrule the
1485translate() function to do nothing: >
1486
1487 :let uk2uk = copy(transdict)
1488 :function! uk2uk.translate(line)
1489 : return a:line
1490 :endfunction
1491 :echo uk2uk.translate('three one wladiwostok')
1492< three one wladiwostok ~
1493
1494Notice that a ! was used to overwrite the existing function reference. Now
1495use "uk2uk" when no recognized language is found: >
1496
1497 :if $LANG =~ "de"
1498 : let trans = uk2de
1499 :elseif $LANG =~ "nl"
1500 : let trans = uk2nl
1501 :else
1502 : let trans = uk2uk
1503 :endif
1504 :echo trans.translate('one two three')
1505< one two three ~
1506
1507For further reading see |Lists| and |Dictionaries|.
1508
1509==============================================================================
1510*41.9* Exceptions
Bram Moolenaar071d4272004-06-13 20:20:40 +00001511
1512Let's start with an example: >
1513
1514 :try
1515 : read ~/templates/pascal.tmpl
1516 :catch /E484:/
1517 : echo "Sorry, the Pascal template file cannot be found."
1518 :endtry
1519
1520The ":read" command will fail if the file does not exist. Instead of
1521generating an error message, this code catches the error and gives the user a
Bram Moolenaar00654022011-02-25 14:42:19 +01001522nice message.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001523
1524For the commands in between ":try" and ":endtry" errors are turned into
1525exceptions. An exception is a string. In the case of an error the string
1526contains the error message. And every error message has a number. In this
1527case, the error we catch contains "E484:". This number is guaranteed to stay
1528the same (the text may change, e.g., it may be translated).
1529
1530When the ":read" command causes another error, the pattern "E484:" will not
1531match in it. Thus this exception will not be caught and result in the usual
1532error message.
1533
1534You might be tempted to do this: >
1535
1536 :try
1537 : read ~/templates/pascal.tmpl
1538 :catch
1539 : echo "Sorry, the Pascal template file cannot be found."
1540 :endtry
1541
1542This means all errors are caught. But then you will not see errors that are
1543useful, such as "E21: Cannot make changes, 'modifiable' is off".
1544
1545Another useful mechanism is the ":finally" command: >
1546
1547 :let tmp = tempname()
1548 :try
1549 : exe ".,$write " . tmp
1550 : exe "!filter " . tmp
1551 : .,$delete
1552 : exe "$read " . tmp
1553 :finally
1554 : call delete(tmp)
1555 :endtry
1556
1557This filters the lines from the cursor until the end of the file through the
1558"filter" command, which takes a file name argument. No matter if the
1559filtering works, something goes wrong in between ":try" and ":finally" or the
1560user cancels the filtering by pressing CTRL-C, the "call delete(tmp)" is
1561always executed. This makes sure you don't leave the temporary file behind.
1562
1563More information about exception handling can be found in the reference
1564manual: |exception-handling|.
1565
1566==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00001567*41.10* Various remarks
Bram Moolenaar071d4272004-06-13 20:20:40 +00001568
1569Here is a summary of items that apply to Vim scripts. They are also mentioned
1570elsewhere, but form a nice checklist.
1571
1572The end-of-line character depends on the system. For Unix a single <NL>
1573character is used. For MS-DOS, Windows, OS/2 and the like, <CR><LF> is used.
1574This is important when using mappings that end in a <CR>. See |:source_crnl|.
1575
1576
1577WHITE SPACE
1578
1579Blank lines are allowed and ignored.
1580
1581Leading whitespace characters (blanks and TABs) are always ignored. The
1582whitespaces between parameters (e.g. between the 'set' and the 'cpoptions' in
1583the example below) are reduced to one blank character and plays the role of a
1584separator, the whitespaces after the last (visible) character may or may not
1585be ignored depending on the situation, see below.
1586
1587For a ":set" command involving the "=" (equal) sign, such as in: >
1588
1589 :set cpoptions =aABceFst
1590
1591the whitespace immediately before the "=" sign is ignored. But there can be
1592no whitespace after the "=" sign!
1593
1594To include a whitespace character in the value of an option, it must be
1595escaped by a "\" (backslash) as in the following example: >
1596
1597 :set tags=my\ nice\ file
1598
Bram Moolenaar00654022011-02-25 14:42:19 +01001599The same example written as: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001600
1601 :set tags=my nice file
1602
1603will issue an error, because it is interpreted as: >
1604
1605 :set tags=my
1606 :set nice
1607 :set file
1608
1609
1610COMMENTS
1611
1612The character " (the double quote mark) starts a comment. Everything after
1613and including this character until the end-of-line is considered a comment and
1614is ignored, except for commands that don't consider comments, as shown in
1615examples below. A comment can start on any character position on the line.
1616
1617There is a little "catch" with comments for some commands. Examples: >
1618
1619 :abbrev dev development " shorthand
1620 :map <F3> o#include " insert include
1621 :execute cmd " do it
1622 :!ls *.c " list C files
1623
1624The abbreviation 'dev' will be expanded to 'development " shorthand'. The
1625mapping of <F3> will actually be the whole line after the 'o# ....' including
1626the '" insert include'. The "execute" command will give an error. The "!"
1627command will send everything after it to the shell, causing an error for an
1628unmatched '"' character.
1629 There can be no comment after ":map", ":abbreviate", ":execute" and "!"
1630commands (there are a few more commands with this restriction). For the
1631":map", ":abbreviate" and ":execute" commands there is a trick: >
1632
1633 :abbrev dev development|" shorthand
1634 :map <F3> o#include|" insert include
1635 :execute cmd |" do it
1636
1637With the '|' character the command is separated from the next one. And that
Bram Moolenaar9e1d2832007-05-06 12:51:41 +00001638next command is only a comment. For the last command you need to do two
1639things: |:execute| and use '|': >
1640 :exe '!ls *.c' |" list C files
Bram Moolenaar071d4272004-06-13 20:20:40 +00001641
1642Notice that there is no white space before the '|' in the abbreviation and
1643mapping. For these commands, any character until the end-of-line or '|' is
1644included. As a consequence of this behavior, you don't always see that
1645trailing whitespace is included: >
1646
1647 :map <F4> o#include
1648
Bram Moolenaar9e1d2832007-05-06 12:51:41 +00001649To spot these problems, you can set the 'list' option when editing vimrc
Bram Moolenaar071d4272004-06-13 20:20:40 +00001650files.
1651
Bram Moolenaar9e1d2832007-05-06 12:51:41 +00001652For Unix there is one special way to comment a line, that allows making a Vim
1653script executable: >
1654 #!/usr/bin/env vim -S
1655 echo "this is a Vim script"
1656 quit
1657
1658The "#" command by itself lists a line with the line number. Adding an
1659exclamation mark changes it into doing nothing, so that you can add the shell
1660command to execute the rest of the file. |:#!| |-S|
1661
Bram Moolenaar071d4272004-06-13 20:20:40 +00001662
1663PITFALLS
1664
1665Even bigger problem arises in the following example: >
1666
1667 :map ,ab o#include
1668 :unmap ,ab
1669
1670Here the unmap command will not work, because it tries to unmap ",ab ". This
1671does not exist as a mapped sequence. An error will be issued, which is very
1672hard to identify, because the ending whitespace character in ":unmap ,ab " is
1673not visible.
1674
1675And this is the same as what happens when one uses a comment after an 'unmap'
1676command: >
1677
1678 :unmap ,ab " comment
1679
1680Here the comment part will be ignored. However, Vim will try to unmap
1681',ab ', which does not exist. Rewrite it as: >
1682
1683 :unmap ,ab| " comment
1684
1685
1686RESTORING THE VIEW
1687
Bram Moolenaar3a0d8092012-10-21 03:02:54 +02001688Sometimes you want to make a change and go back to where the cursor was.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001689Restoring the relative position would also be nice, so that the same line
1690appears at the top of the window.
1691 This example yanks the current line, puts it above the first line in the
1692file and then restores the view: >
1693
1694 map ,p ma"aYHmbgg"aP`bzt`a
1695
1696What this does: >
1697 ma"aYHmbgg"aP`bzt`a
1698< ma set mark a at cursor position
1699 "aY yank current line into register a
1700 Hmb go to top line in window and set mark b there
1701 gg go to first line in file
1702 "aP put the yanked line above it
1703 `b go back to top line in display
1704 zt position the text in the window as before
1705 `a go back to saved cursor position
1706
1707
1708PACKAGING
1709
1710To avoid your function names to interfere with functions that you get from
1711others, use this scheme:
1712- Prepend a unique string before each function name. I often use an
1713 abbreviation. For example, "OW_" is used for the option window functions.
1714- Put the definition of your functions together in a file. Set a global
1715 variable to indicate that the functions have been loaded. When sourcing the
1716 file again, first unload the functions.
1717Example: >
1718
1719 " This is the XXX package
1720
1721 if exists("XXX_loaded")
1722 delfun XXX_one
1723 delfun XXX_two
1724 endif
1725
1726 function XXX_one(a)
1727 ... body of function ...
1728 endfun
1729
1730 function XXX_two(b)
1731 ... body of function ...
1732 endfun
1733
1734 let XXX_loaded = 1
1735
1736==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00001737*41.11* Writing a plugin *write-plugin*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001738
1739You can write a Vim script in such a way that many people can use it. This is
1740called a plugin. Vim users can drop your script in their plugin directory and
1741use its features right away |add-plugin|.
1742
1743There are actually two types of plugins:
1744
1745 global plugins: For all types of files.
1746filetype plugins: Only for files of a specific type.
1747
1748In this section the first type is explained. Most items are also relevant for
1749writing filetype plugins. The specifics for filetype plugins are in the next
1750section |write-filetype-plugin|.
1751
1752
1753NAME
1754
1755First of all you must choose a name for your plugin. The features provided
1756by the plugin should be clear from its name. And it should be unlikely that
1757someone else writes a plugin with the same name but which does something
1758different. And please limit the name to 8 characters, to avoid problems on
1759old Windows systems.
1760
1761A script that corrects typing mistakes could be called "typecorr.vim". We
1762will use it here as an example.
1763
1764For the plugin to work for everybody, it should follow a few guidelines. This
1765will be explained step-by-step. The complete example plugin is at the end.
1766
1767
1768BODY
1769
1770Let's start with the body of the plugin, the lines that do the actual work: >
1771
1772 14 iabbrev teh the
1773 15 iabbrev otehr other
1774 16 iabbrev wnat want
1775 17 iabbrev synchronisation
1776 18 \ synchronization
1777 19 let s:count = 4
1778
1779The actual list should be much longer, of course.
1780
1781The line numbers have only been added to explain a few things, don't put them
1782in your plugin file!
1783
1784
1785HEADER
1786
1787You will probably add new corrections to the plugin and soon have several
Bram Moolenaard09acef2012-09-21 14:54:30 +02001788versions lying around. And when distributing this file, people will want to
Bram Moolenaar071d4272004-06-13 20:20:40 +00001789know who wrote this wonderful plugin and where they can send remarks.
1790Therefore, put a header at the top of your plugin: >
1791
1792 1 " Vim global plugin for correcting typing mistakes
1793 2 " Last Change: 2000 Oct 15
1794 3 " Maintainer: Bram Moolenaar <Bram@vim.org>
1795
1796About copyright and licensing: Since plugins are very useful and it's hardly
1797worth restricting their distribution, please consider making your plugin
1798either public domain or use the Vim |license|. A short note about this near
1799the top of the plugin should be sufficient. Example: >
1800
1801 4 " License: This file is placed in the public domain.
1802
1803
1804LINE CONTINUATION, AVOIDING SIDE EFFECTS *use-cpo-save*
1805
1806In line 18 above, the line-continuation mechanism is used |line-continuation|.
1807Users with 'compatible' set will run into trouble here, they will get an error
1808message. We can't just reset 'compatible', because that has a lot of side
1809effects. To avoid this, we will set the 'cpoptions' option to its Vim default
1810value and restore it later. That will allow the use of line-continuation and
1811make the script work for most people. It is done like this: >
1812
1813 11 let s:save_cpo = &cpo
1814 12 set cpo&vim
1815 ..
1816 42 let &cpo = s:save_cpo
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02001817 43 unlet s:save_cpo
Bram Moolenaar071d4272004-06-13 20:20:40 +00001818
1819We first store the old value of 'cpoptions' in the s:save_cpo variable. At
1820the end of the plugin this value is restored.
1821
1822Notice that a script-local variable is used |s:var|. A global variable could
1823already be in use for something else. Always use script-local variables for
1824things that are only used in the script.
1825
1826
1827NOT LOADING
1828
1829It's possible that a user doesn't always want to load this plugin. Or the
1830system administrator has dropped it in the system-wide plugin directory, but a
1831user has his own plugin he wants to use. Then the user must have a chance to
1832disable loading this specific plugin. This will make it possible: >
1833
Bram Moolenaarc5604bc2010-07-17 15:20:30 +02001834 6 if exists("g:loaded_typecorr")
Bram Moolenaar071d4272004-06-13 20:20:40 +00001835 7 finish
1836 8 endif
Bram Moolenaarc5604bc2010-07-17 15:20:30 +02001837 9 let g:loaded_typecorr = 1
Bram Moolenaar071d4272004-06-13 20:20:40 +00001838
1839This also avoids that when the script is loaded twice it would cause error
1840messages for redefining functions and cause trouble for autocommands that are
1841added twice.
1842
Bram Moolenaarc5604bc2010-07-17 15:20:30 +02001843The name is recommended to start with "loaded_" and then the file name of the
1844plugin, literally. The "g:" is prepended just to avoid mistakes when using
1845the variable in a function (without "g:" it would be a variable local to the
1846function).
1847
1848Using "finish" stops Vim from reading the rest of the file, it's much quicker
1849than using if-endif around the whole file.
1850
Bram Moolenaar071d4272004-06-13 20:20:40 +00001851
1852MAPPING
1853
1854Now let's make the plugin more interesting: We will add a mapping that adds a
1855correction for the word under the cursor. We could just pick a key sequence
1856for this mapping, but the user might already use it for something else. To
1857allow the user to define which keys a mapping in a plugin uses, the <Leader>
1858item can be used: >
1859
1860 22 map <unique> <Leader>a <Plug>TypecorrAdd
1861
1862The "<Plug>TypecorrAdd" thing will do the work, more about that further on.
1863
1864The user can set the "mapleader" variable to the key sequence that he wants
1865this mapping to start with. Thus if the user has done: >
1866
1867 let mapleader = "_"
1868
1869the mapping will define "_a". If the user didn't do this, the default value
1870will be used, which is a backslash. Then a map for "\a" will be defined.
1871
1872Note that <unique> is used, this will cause an error message if the mapping
1873already happened to exist. |:map-<unique>|
1874
1875But what if the user wants to define his own key sequence? We can allow that
1876with this mechanism: >
1877
1878 21 if !hasmapto('<Plug>TypecorrAdd')
1879 22 map <unique> <Leader>a <Plug>TypecorrAdd
1880 23 endif
1881
1882This checks if a mapping to "<Plug>TypecorrAdd" already exists, and only
1883defines the mapping from "<Leader>a" if it doesn't. The user then has a
1884chance of putting this in his vimrc file: >
1885
1886 map ,c <Plug>TypecorrAdd
1887
1888Then the mapped key sequence will be ",c" instead of "_a" or "\a".
1889
1890
1891PIECES
1892
1893If a script gets longer, you often want to break up the work in pieces. You
1894can use functions or mappings for this. But you don't want these functions
1895and mappings to interfere with the ones from other scripts. For example, you
1896could define a function Add(), but another script could try to define the same
1897function. To avoid this, we define the function local to the script by
1898prepending it with "s:".
1899
1900We will define a function that adds a new typing correction: >
1901
1902 30 function s:Add(from, correct)
1903 31 let to = input("type the correction for " . a:from . ": ")
1904 32 exe ":iabbrev " . a:from . " " . to
1905 ..
1906 36 endfunction
1907
1908Now we can call the function s:Add() from within this script. If another
1909script also defines s:Add(), it will be local to that script and can only
1910be called from the script it was defined in. There can also be a global Add()
1911function (without the "s:"), which is again another function.
1912
1913<SID> can be used with mappings. It generates a script ID, which identifies
1914the current script. In our typing correction plugin we use it like this: >
1915
1916 24 noremap <unique> <script> <Plug>TypecorrAdd <SID>Add
1917 ..
1918 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), 1)<CR>
1919
1920Thus when a user types "\a", this sequence is invoked: >
1921
1922 \a -> <Plug>TypecorrAdd -> <SID>Add -> :call <SID>Add()
1923
1924If another script would also map <SID>Add, it would get another script ID and
1925thus define another mapping.
1926
1927Note that instead of s:Add() we use <SID>Add() here. That is because the
1928mapping is typed by the user, thus outside of the script. The <SID> is
1929translated to the script ID, so that Vim knows in which script to look for
1930the Add() function.
1931
1932This is a bit complicated, but it's required for the plugin to work together
1933with other plugins. The basic rule is that you use <SID>Add() in mappings and
1934s:Add() in other places (the script itself, autocommands, user commands).
1935
1936We can also add a menu entry to do the same as the mapping: >
1937
1938 26 noremenu <script> Plugin.Add\ Correction <SID>Add
1939
1940The "Plugin" menu is recommended for adding menu items for plugins. In this
1941case only one item is used. When adding more items, creating a submenu is
1942recommended. For example, "Plugin.CVS" could be used for a plugin that offers
1943CVS operations "Plugin.CVS.checkin", "Plugin.CVS.checkout", etc.
1944
1945Note that in line 28 ":noremap" is used to avoid that any other mappings cause
1946trouble. Someone may have remapped ":call", for example. In line 24 we also
1947use ":noremap", but we do want "<SID>Add" to be remapped. This is why
1948"<script>" is used here. This only allows mappings which are local to the
1949script. |:map-<script>| The same is done in line 26 for ":noremenu".
1950|:menu-<script>|
1951
1952
1953<SID> AND <Plug> *using-<Plug>*
1954
1955Both <SID> and <Plug> are used to avoid that mappings of typed keys interfere
1956with mappings that are only to be used from other mappings. Note the
1957difference between using <SID> and <Plug>:
1958
1959<Plug> is visible outside of the script. It is used for mappings which the
1960 user might want to map a key sequence to. <Plug> is a special code
1961 that a typed key will never produce.
1962 To make it very unlikely that other plugins use the same sequence of
1963 characters, use this structure: <Plug> scriptname mapname
1964 In our example the scriptname is "Typecorr" and the mapname is "Add".
1965 This results in "<Plug>TypecorrAdd". Only the first character of
1966 scriptname and mapname is uppercase, so that we can see where mapname
1967 starts.
1968
1969<SID> is the script ID, a unique identifier for a script.
1970 Internally Vim translates <SID> to "<SNR>123_", where "123" can be any
1971 number. Thus a function "<SID>Add()" will have a name "<SNR>11_Add()"
1972 in one script, and "<SNR>22_Add()" in another. You can see this if
1973 you use the ":function" command to get a list of functions. The
1974 translation of <SID> in mappings is exactly the same, that's how you
1975 can call a script-local function from a mapping.
1976
1977
1978USER COMMAND
1979
1980Now let's add a user command to add a correction: >
1981
1982 38 if !exists(":Correct")
1983 39 command -nargs=1 Correct :call s:Add(<q-args>, 0)
1984 40 endif
1985
1986The user command is defined only if no command with the same name already
1987exists. Otherwise we would get an error here. Overriding the existing user
1988command with ":command!" is not a good idea, this would probably make the user
1989wonder why the command he defined himself doesn't work. |:command|
1990
1991
1992SCRIPT VARIABLES
1993
1994When a variable starts with "s:" it is a script variable. It can only be used
1995inside a script. Outside the script it's not visible. This avoids trouble
1996with using the same variable name in different scripts. The variables will be
1997kept as long as Vim is running. And the same variables are used when sourcing
1998the same script again. |s:var|
1999
2000The fun is that these variables can also be used in functions, autocommands
2001and user commands that are defined in the script. In our example we can add
2002a few lines to count the number of corrections: >
2003
2004 19 let s:count = 4
2005 ..
2006 30 function s:Add(from, correct)
2007 ..
2008 34 let s:count = s:count + 1
2009 35 echo s:count . " corrections now"
2010 36 endfunction
2011
2012First s:count is initialized to 4 in the script itself. When later the
2013s:Add() function is called, it increments s:count. It doesn't matter from
2014where the function was called, since it has been defined in the script, it
2015will use the local variables from this script.
2016
2017
2018THE RESULT
2019
2020Here is the resulting complete example: >
2021
2022 1 " Vim global plugin for correcting typing mistakes
2023 2 " Last Change: 2000 Oct 15
2024 3 " Maintainer: Bram Moolenaar <Bram@vim.org>
2025 4 " License: This file is placed in the public domain.
2026 5
Bram Moolenaarc5604bc2010-07-17 15:20:30 +02002027 6 if exists("g:loaded_typecorr")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002028 7 finish
2029 8 endif
Bram Moolenaarc5604bc2010-07-17 15:20:30 +02002030 9 let g:loaded_typecorr = 1
Bram Moolenaar071d4272004-06-13 20:20:40 +00002031 10
2032 11 let s:save_cpo = &cpo
2033 12 set cpo&vim
2034 13
2035 14 iabbrev teh the
2036 15 iabbrev otehr other
2037 16 iabbrev wnat want
2038 17 iabbrev synchronisation
2039 18 \ synchronization
2040 19 let s:count = 4
2041 20
2042 21 if !hasmapto('<Plug>TypecorrAdd')
2043 22 map <unique> <Leader>a <Plug>TypecorrAdd
2044 23 endif
2045 24 noremap <unique> <script> <Plug>TypecorrAdd <SID>Add
2046 25
2047 26 noremenu <script> Plugin.Add\ Correction <SID>Add
2048 27
2049 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), 1)<CR>
2050 29
2051 30 function s:Add(from, correct)
2052 31 let to = input("type the correction for " . a:from . ": ")
2053 32 exe ":iabbrev " . a:from . " " . to
2054 33 if a:correct | exe "normal viws\<C-R>\" \b\e" | endif
2055 34 let s:count = s:count + 1
2056 35 echo s:count . " corrections now"
2057 36 endfunction
2058 37
2059 38 if !exists(":Correct")
2060 39 command -nargs=1 Correct :call s:Add(<q-args>, 0)
2061 40 endif
2062 41
2063 42 let &cpo = s:save_cpo
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02002064 43 unlet s:save_cpo
Bram Moolenaar071d4272004-06-13 20:20:40 +00002065
2066Line 33 wasn't explained yet. It applies the new correction to the word under
2067the cursor. The |:normal| command is used to use the new abbreviation. Note
2068that mappings and abbreviations are expanded here, even though the function
2069was called from a mapping defined with ":noremap".
2070
2071Using "unix" for the 'fileformat' option is recommended. The Vim scripts will
2072then work everywhere. Scripts with 'fileformat' set to "dos" do not work on
2073Unix. Also see |:source_crnl|. To be sure it is set right, do this before
2074writing the file: >
2075
2076 :set fileformat=unix
2077
2078
2079DOCUMENTATION *write-local-help*
2080
2081It's a good idea to also write some documentation for your plugin. Especially
2082when its behavior can be changed by the user. See |add-local-help| for how
2083they are installed.
2084
2085Here is a simple example for a plugin help file, called "typecorr.txt": >
2086
2087 1 *typecorr.txt* Plugin for correcting typing mistakes
2088 2
2089 3 If you make typing mistakes, this plugin will have them corrected
2090 4 automatically.
2091 5
2092 6 There are currently only a few corrections. Add your own if you like.
2093 7
2094 8 Mappings:
2095 9 <Leader>a or <Plug>TypecorrAdd
2096 10 Add a correction for the word under the cursor.
2097 11
2098 12 Commands:
2099 13 :Correct {word}
2100 14 Add a correction for {word}.
2101 15
2102 16 *typecorr-settings*
2103 17 This plugin doesn't have any settings.
2104
2105The first line is actually the only one for which the format matters. It will
2106be extracted from the help file to be put in the "LOCAL ADDITIONS:" section of
2107help.txt |local-additions|. The first "*" must be in the first column of the
2108first line. After adding your help file do ":help" and check that the entries
2109line up nicely.
2110
2111You can add more tags inside ** in your help file. But be careful not to use
2112existing help tags. You would probably use the name of your plugin in most of
2113them, like "typecorr-settings" in the example.
2114
2115Using references to other parts of the help in || is recommended. This makes
2116it easy for the user to find associated help.
2117
2118
2119FILETYPE DETECTION *plugin-filetype*
2120
2121If your filetype is not already detected by Vim, you should create a filetype
2122detection snippet in a separate file. It is usually in the form of an
2123autocommand that sets the filetype when the file name matches a pattern.
2124Example: >
2125
2126 au BufNewFile,BufRead *.foo set filetype=foofoo
2127
2128Write this single-line file as "ftdetect/foofoo.vim" in the first directory
2129that appears in 'runtimepath'. For Unix that would be
2130"~/.vim/ftdetect/foofoo.vim". The convention is to use the name of the
2131filetype for the script name.
2132
2133You can make more complicated checks if you like, for example to inspect the
2134contents of the file to recognize the language. Also see |new-filetype|.
2135
2136
2137SUMMARY *plugin-special*
2138
2139Summary of special things to use in a plugin:
2140
2141s:name Variables local to the script.
2142
2143<SID> Script-ID, used for mappings and functions local to
2144 the script.
2145
2146hasmapto() Function to test if the user already defined a mapping
2147 for functionality the script offers.
2148
2149<Leader> Value of "mapleader", which the user defines as the
2150 keys that plugin mappings start with.
2151
2152:map <unique> Give a warning if a mapping already exists.
2153
2154:noremap <script> Use only mappings local to the script, not global
2155 mappings.
2156
2157exists(":Cmd") Check if a user command already exists.
2158
2159==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00002160*41.12* Writing a filetype plugin *write-filetype-plugin* *ftplugin*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002161
2162A filetype plugin is like a global plugin, except that it sets options and
2163defines mappings for the current buffer only. See |add-filetype-plugin| for
2164how this type of plugin is used.
2165
Bram Moolenaar7c626922005-02-07 22:01:03 +00002166First read the section on global plugins above |41.11|. All that is said there
Bram Moolenaar071d4272004-06-13 20:20:40 +00002167also applies to filetype plugins. There are a few extras, which are explained
2168here. The essential thing is that a filetype plugin should only have an
2169effect on the current buffer.
2170
2171
2172DISABLING
2173
2174If you are writing a filetype plugin to be used by many people, they need a
2175chance to disable loading it. Put this at the top of the plugin: >
2176
2177 " Only do this when not done yet for this buffer
2178 if exists("b:did_ftplugin")
2179 finish
2180 endif
2181 let b:did_ftplugin = 1
2182
2183This also needs to be used to avoid that the same plugin is executed twice for
2184the same buffer (happens when using an ":edit" command without arguments).
2185
2186Now users can disable loading the default plugin completely by making a
2187filetype plugin with only this line: >
2188
2189 let b:did_ftplugin = 1
2190
2191This does require that the filetype plugin directory comes before $VIMRUNTIME
2192in 'runtimepath'!
2193
2194If you do want to use the default plugin, but overrule one of the settings,
2195you can write the different setting in a script: >
2196
2197 setlocal textwidth=70
2198
2199Now write this in the "after" directory, so that it gets sourced after the
2200distributed "vim.vim" ftplugin |after-directory|. For Unix this would be
2201"~/.vim/after/ftplugin/vim.vim". Note that the default plugin will have set
2202"b:did_ftplugin", but it is ignored here.
2203
2204
2205OPTIONS
2206
2207To make sure the filetype plugin only affects the current buffer use the >
2208
2209 :setlocal
2210
2211command to set options. And only set options which are local to a buffer (see
2212the help for the option to check that). When using |:setlocal| for global
2213options or options local to a window, the value will change for many buffers,
2214and that is not what a filetype plugin should do.
2215
2216When an option has a value that is a list of flags or items, consider using
2217"+=" and "-=" to keep the existing value. Be aware that the user may have
2218changed an option value already. First resetting to the default value and
Bram Moolenaard58e9292011-02-09 17:07:58 +01002219then changing it is often a good idea. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002220
2221 :setlocal formatoptions& formatoptions+=ro
2222
2223
2224MAPPINGS
2225
2226To make sure mappings will only work in the current buffer use the >
2227
2228 :map <buffer>
2229
2230command. This needs to be combined with the two-step mapping explained above.
2231An example of how to define functionality in a filetype plugin: >
2232
2233 if !hasmapto('<Plug>JavaImport')
2234 map <buffer> <unique> <LocalLeader>i <Plug>JavaImport
2235 endif
2236 noremap <buffer> <unique> <Plug>JavaImport oimport ""<Left><Esc>
2237
2238|hasmapto()| is used to check if the user has already defined a map to
2239<Plug>JavaImport. If not, then the filetype plugin defines the default
2240mapping. This starts with |<LocalLeader>|, which allows the user to select
2241the key(s) he wants filetype plugin mappings to start with. The default is a
2242backslash.
2243"<unique>" is used to give an error message if the mapping already exists or
2244overlaps with an existing mapping.
2245|:noremap| is used to avoid that any other mappings that the user has defined
2246interferes. You might want to use ":noremap <script>" to allow remapping
2247mappings defined in this script that start with <SID>.
2248
2249The user must have a chance to disable the mappings in a filetype plugin,
2250without disabling everything. Here is an example of how this is done for a
2251plugin for the mail filetype: >
2252
2253 " Add mappings, unless the user didn't want this.
2254 if !exists("no_plugin_maps") && !exists("no_mail_maps")
2255 " Quote text by inserting "> "
2256 if !hasmapto('<Plug>MailQuote')
2257 vmap <buffer> <LocalLeader>q <Plug>MailQuote
2258 nmap <buffer> <LocalLeader>q <Plug>MailQuote
2259 endif
2260 vnoremap <buffer> <Plug>MailQuote :s/^/> /<CR>
2261 nnoremap <buffer> <Plug>MailQuote :.,$s/^/> /<CR>
2262 endif
2263
2264Two global variables are used:
2265no_plugin_maps disables mappings for all filetype plugins
2266no_mail_maps disables mappings for a specific filetype
2267
2268
2269USER COMMANDS
2270
2271To add a user command for a specific file type, so that it can only be used in
2272one buffer, use the "-buffer" argument to |:command|. Example: >
2273
2274 :command -buffer Make make %:r.s
2275
2276
2277VARIABLES
2278
2279A filetype plugin will be sourced for each buffer of the type it's for. Local
2280script variables |s:var| will be shared between all invocations. Use local
2281buffer variables |b:var| if you want a variable specifically for one buffer.
2282
2283
2284FUNCTIONS
2285
2286When defining a function, this only needs to be done once. But the filetype
2287plugin will be sourced every time a file with this filetype will be opened.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02002288This construct makes sure the function is only defined once: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002289
2290 :if !exists("*s:Func")
2291 : function s:Func(arg)
2292 : ...
2293 : endfunction
2294 :endif
2295<
2296
Bram Moolenaar38a55632016-02-15 22:07:32 +01002297UNDO *undo_indent* *undo_ftplugin*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002298
2299When the user does ":setfiletype xyz" the effect of the previous filetype
2300should be undone. Set the b:undo_ftplugin variable to the commands that will
2301undo the settings in your filetype plugin. Example: >
2302
2303 let b:undo_ftplugin = "setlocal fo< com< tw< commentstring<"
2304 \ . "| unlet b:match_ignorecase b:match_words b:match_skip"
2305
2306Using ":setlocal" with "<" after the option name resets the option to its
2307global value. That is mostly the best way to reset the option value.
2308
2309This does require removing the "C" flag from 'cpoptions' to allow line
2310continuation, as mentioned above |use-cpo-save|.
2311
Bram Moolenaar38a55632016-02-15 22:07:32 +01002312For undoing the effect of an indent script, the b:undo_indent variable should
2313be set accordingly.
2314
Bram Moolenaar071d4272004-06-13 20:20:40 +00002315
2316FILE NAME
2317
2318The filetype must be included in the file name |ftplugin-name|. Use one of
2319these three forms:
2320
2321 .../ftplugin/stuff.vim
2322 .../ftplugin/stuff_foo.vim
2323 .../ftplugin/stuff/bar.vim
2324
2325"stuff" is the filetype, "foo" and "bar" are arbitrary names.
2326
2327
2328SUMMARY *ftplugin-special*
2329
2330Summary of special things to use in a filetype plugin:
2331
2332<LocalLeader> Value of "maplocalleader", which the user defines as
2333 the keys that filetype plugin mappings start with.
2334
2335:map <buffer> Define a mapping local to the buffer.
2336
2337:noremap <script> Only remap mappings defined in this script that start
2338 with <SID>.
2339
2340:setlocal Set an option for the current buffer only.
2341
2342:command -buffer Define a user command local to the buffer.
2343
2344exists("*s:Func") Check if a function was already defined.
2345
2346Also see |plugin-special|, the special things used for all plugins.
2347
2348==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00002349*41.13* Writing a compiler plugin *write-compiler-plugin*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002350
2351A compiler plugin sets options for use with a specific compiler. The user can
2352load it with the |:compiler| command. The main use is to set the
2353'errorformat' and 'makeprg' options.
2354
2355Easiest is to have a look at examples. This command will edit all the default
2356compiler plugins: >
2357
2358 :next $VIMRUNTIME/compiler/*.vim
2359
2360Use |:next| to go to the next plugin file.
2361
2362There are two special items about these files. First is a mechanism to allow
2363a user to overrule or add to the default file. The default files start with: >
2364
2365 :if exists("current_compiler")
2366 : finish
2367 :endif
2368 :let current_compiler = "mine"
2369
2370When you write a compiler file and put it in your personal runtime directory
2371(e.g., ~/.vim/compiler for Unix), you set the "current_compiler" variable to
2372make the default file skip the settings.
Bram Moolenaarc6039d82005-12-02 00:44:04 +00002373 *:CompilerSet*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002374The second mechanism is to use ":set" for ":compiler!" and ":setlocal" for
2375":compiler". Vim defines the ":CompilerSet" user command for this. However,
2376older Vim versions don't, thus your plugin should define it then. This is an
2377example: >
2378
2379 if exists(":CompilerSet") != 2
2380 command -nargs=* CompilerSet setlocal <args>
2381 endif
2382 CompilerSet errorformat& " use the default 'errorformat'
2383 CompilerSet makeprg=nmake
2384
2385When you write a compiler plugin for the Vim distribution or for a system-wide
2386runtime directory, use the mechanism mentioned above. When
2387"current_compiler" was already set by a user plugin nothing will be done.
2388
2389When you write a compiler plugin to overrule settings from a default plugin,
2390don't check "current_compiler". This plugin is supposed to be loaded
2391last, thus it should be in a directory at the end of 'runtimepath'. For Unix
2392that could be ~/.vim/after/compiler.
2393
2394==============================================================================
Bram Moolenaar05159a02005-02-26 23:04:13 +00002395*41.14* Writing a plugin that loads quickly *write-plugin-quickload*
2396
2397A plugin may grow and become quite long. The startup delay may become
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00002398noticeable, while you hardly ever use the plugin. Then it's time for a
Bram Moolenaar05159a02005-02-26 23:04:13 +00002399quickload plugin.
2400
2401The basic idea is that the plugin is loaded twice. The first time user
2402commands and mappings are defined that offer the functionality. The second
2403time the functions that implement the functionality are defined.
2404
2405It may sound surprising that quickload means loading a script twice. What we
2406mean is that it loads quickly the first time, postponing the bulk of the
2407script to the second time, which only happens when you actually use it. When
2408you always use the functionality it actually gets slower!
2409
Bram Moolenaar76916e62006-03-21 21:23:25 +00002410Note that since Vim 7 there is an alternative: use the |autoload|
2411functionality |41.15|.
2412
Bram Moolenaar05159a02005-02-26 23:04:13 +00002413The following example shows how it's done: >
2414
2415 " Vim global plugin for demonstrating quick loading
2416 " Last Change: 2005 Feb 25
2417 " Maintainer: Bram Moolenaar <Bram@vim.org>
2418 " License: This file is placed in the public domain.
2419
2420 if !exists("s:did_load")
2421 command -nargs=* BNRead call BufNetRead(<f-args>)
2422 map <F19> :call BufNetWrite('something')<CR>
2423
2424 let s:did_load = 1
2425 exe 'au FuncUndefined BufNet* source ' . expand('<sfile>')
2426 finish
2427 endif
2428
2429 function BufNetRead(...)
2430 echo 'BufNetRead(' . string(a:000) . ')'
2431 " read functionality here
2432 endfunction
2433
2434 function BufNetWrite(...)
2435 echo 'BufNetWrite(' . string(a:000) . ')'
2436 " write functionality here
2437 endfunction
2438
2439When the script is first loaded "s:did_load" is not set. The commands between
2440the "if" and "endif" will be executed. This ends in a |:finish| command, thus
2441the rest of the script is not executed.
2442
2443The second time the script is loaded "s:did_load" exists and the commands
2444after the "endif" are executed. This defines the (possible long)
2445BufNetRead() and BufNetWrite() functions.
2446
2447If you drop this script in your plugin directory Vim will execute it on
2448startup. This is the sequence of events that happens:
2449
24501. The "BNRead" command is defined and the <F19> key is mapped when the script
2451 is sourced at startup. A |FuncUndefined| autocommand is defined. The
2452 ":finish" command causes the script to terminate early.
2453
24542. The user types the BNRead command or presses the <F19> key. The
2455 BufNetRead() or BufNetWrite() function will be called.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00002456
Bram Moolenaar05159a02005-02-26 23:04:13 +000024573. Vim can't find the function and triggers the |FuncUndefined| autocommand
2458 event. Since the pattern "BufNet*" matches the invoked function, the
2459 command "source fname" will be executed. "fname" will be equal to the name
2460 of the script, no matter where it is located, because it comes from
2461 expanding "<sfile>" (see |expand()|).
2462
24634. The script is sourced again, the "s:did_load" variable exists and the
2464 functions are defined.
2465
2466Notice that the functions that are loaded afterwards match the pattern in the
2467|FuncUndefined| autocommand. You must make sure that no other plugin defines
2468functions that match this pattern.
2469
2470==============================================================================
2471*41.15* Writing library scripts *write-library-script*
2472
2473Some functionality will be required in several places. When this becomes more
2474than a few lines you will want to put it in one script and use it from many
2475scripts. We will call that one script a library script.
2476
2477Manually loading a library script is possible, so long as you avoid loading it
2478when it's already done. You can do this with the |exists()| function.
2479Example: >
2480
2481 if !exists('*MyLibFunction')
2482 runtime library/mylibscript.vim
2483 endif
2484 call MyLibFunction(arg)
2485
2486Here you need to know that MyLibFunction() is defined in a script
2487"library/mylibscript.vim" in one of the directories in 'runtimepath'.
2488
2489To make this a bit simpler Vim offers the autoload mechanism. Then the
2490example looks like this: >
2491
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002492 call mylib#myfunction(arg)
Bram Moolenaar05159a02005-02-26 23:04:13 +00002493
2494That's a lot simpler, isn't it? Vim will recognize the function name and when
2495it's not defined search for the script "autoload/mylib.vim" in 'runtimepath'.
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002496That script must define the "mylib#myfunction()" function.
Bram Moolenaar05159a02005-02-26 23:04:13 +00002497
2498You can put many other functions in the mylib.vim script, you are free to
2499organize your functions in library scripts. But you must use function names
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00002500where the part before the '#' matches the script name. Otherwise Vim would
2501not know what script to load.
Bram Moolenaar05159a02005-02-26 23:04:13 +00002502
Bram Moolenaard1f56e62006-02-22 21:25:37 +00002503If you get really enthusiastic and write lots of library scripts, you may
Bram Moolenaar05159a02005-02-26 23:04:13 +00002504want to use subdirectories. Example: >
2505
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002506 call netlib#ftp#read('somefile')
Bram Moolenaar05159a02005-02-26 23:04:13 +00002507
2508For Unix the library script used for this could be:
2509
2510 ~/.vim/autoload/netlib/ftp.vim
2511
2512Where the function is defined like this: >
2513
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002514 function netlib#ftp#read(fname)
Bram Moolenaar05159a02005-02-26 23:04:13 +00002515 " Read the file fname through ftp
2516 endfunction
2517
2518Notice that the name the function is defined with is exactly the same as the
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00002519name used for calling the function. And the part before the last '#'
Bram Moolenaar05159a02005-02-26 23:04:13 +00002520exactly matches the subdirectory and script name.
2521
2522You can use the same mechanism for variables: >
2523
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002524 let weekdays = dutch#weekdays
Bram Moolenaar05159a02005-02-26 23:04:13 +00002525
2526This will load the script "autoload/dutch.vim", which should contain something
2527like: >
2528
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002529 let dutch#weekdays = ['zondag', 'maandag', 'dinsdag', 'woensdag',
Bram Moolenaar05159a02005-02-26 23:04:13 +00002530 \ 'donderdag', 'vrijdag', 'zaterdag']
2531
2532Further reading: |autoload|.
2533
2534==============================================================================
Bram Moolenaar76916e62006-03-21 21:23:25 +00002535*41.16* Distributing Vim scripts *distribute-script*
2536
2537Vim users will look for scripts on the Vim website: http://www.vim.org.
2538If you made something that is useful for others, share it!
2539
2540Vim scripts can be used on any system. There might not be a tar or gzip
2541command. If you want to pack files together and/or compress them the "zip"
2542utility is recommended.
2543
2544For utmost portability use Vim itself to pack scripts together. This can be
2545done with the Vimball utility. See |vimball|.
2546
Bram Moolenaarc01140a2006-03-24 22:21:52 +00002547It's good if you add a line to allow automatic updating. See |glvs-plugins|.
2548
Bram Moolenaar76916e62006-03-21 21:23:25 +00002549==============================================================================
Bram Moolenaar071d4272004-06-13 20:20:40 +00002550
2551Next chapter: |usr_42.txt| Add new menus
2552
2553Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: