blob: cef6fd793a66eb9ad965215a5fd7bb431ccebba8 [file] [log] [blame]
Bram Moolenaarbb8476b2019-05-04 15:47:48 +02001*usr_41.txt* For Vim version 8.1. Last change: 2019 May 04
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 Moolenaar214641f2017-03-05 17:04:09 +010098make such a loop, it can be written much more compact: >
Bram Moolenaaraf7f6412005-01-17 22:11:23 +000099
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 Moolenaar9d401282019-04-06 13:18:12 +0200580 nr2char() get a character by its number value
581 list2str() get a character string from a list of numbers
582 char2nr() get number value of a character
583 str2list() get list of numbers from a string
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000584 str2nr() convert a string to a Number
585 str2float() convert a string to a Float
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000586 printf() format a string according to % items
Bram Moolenaar071d4272004-06-13 20:20:40 +0000587 escape() escape characters in a string with a '\'
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000588 shellescape() escape a string for use with a shell command
589 fnameescape() escape a file name for use with a Vim command
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000590 tr() translate characters from one set to another
Bram Moolenaar071d4272004-06-13 20:20:40 +0000591 strtrans() translate a string to make it printable
592 tolower() turn a string to lowercase
593 toupper() turn a string to uppercase
594 match() position where a pattern matches in a string
595 matchend() position where a pattern match ends in a string
596 matchstr() match of a pattern in a string
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +0200597 matchstrpos() match and positions of a pattern in a string
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000598 matchlist() like matchstr() and also return submatches
Bram Moolenaar071d4272004-06-13 20:20:40 +0000599 stridx() first index of a short string in a long string
600 strridx() last index of a short string in a long string
Bram Moolenaar8d043172014-01-23 14:24:41 +0100601 strlen() length of a string in bytes
602 strchars() length of a string in characters
603 strwidth() size of string when displayed
604 strdisplaywidth() size of string when displayed, deals with tabs
Bram Moolenaar071d4272004-06-13 20:20:40 +0000605 substitute() substitute a pattern match with a string
Bram Moolenaar251e1912011-06-19 05:09:16 +0200606 submatch() get a specific match in ":s" and substitute()
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200607 strpart() get part of a string using byte index
608 strcharpart() get part of a string using char index
609 strgetchar() get character from a string using char index
Bram Moolenaar071d4272004-06-13 20:20:40 +0000610 expand() expand special keywords
Bram Moolenaar071d4272004-06-13 20:20:40 +0000611 iconv() convert text from one encoding to another
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000612 byteidx() byte index of a character in a string
Bram Moolenaar8d043172014-01-23 14:24:41 +0100613 byteidxcomp() like byteidx() but count composing characters
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000614 repeat() repeat a string multiple times
615 eval() evaluate a string expression
Bram Moolenaar063b9d12016-07-09 20:21:48 +0200616 execute() execute an Ex command and get the output
Bram Moolenaarb730f0c2018-11-25 03:56:26 +0100617 trim() trim characters from a string
Bram Moolenaar071d4272004-06-13 20:20:40 +0000618
Bram Moolenaara3f41662010-07-11 19:01:06 +0200619List manipulation: *list-functions*
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000620 get() get an item without error for wrong index
621 len() number of items in a List
622 empty() check if List is empty
623 insert() insert an item somewhere in a List
624 add() append an item to a List
625 extend() append a List to a List
626 remove() remove one or more items from a List
627 copy() make a shallow copy of a List
628 deepcopy() make a full copy of a List
629 filter() remove selected items from a List
630 map() change each List item
631 sort() sort a List
632 reverse() reverse the order of a List
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +0100633 uniq() remove copies of repeated adjacent items
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000634 split() split a String into a List
635 join() join List items into a String
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000636 range() return a List with a sequence of numbers
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000637 string() String representation of a List
638 call() call a function with List as arguments
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000639 index() index of a value in a List
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000640 max() maximum value in a List
641 min() minimum value in a List
642 count() count number of times a value appears in a List
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000643 repeat() repeat a List multiple times
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000644
Bram Moolenaara3f41662010-07-11 19:01:06 +0200645Dictionary manipulation: *dict-functions*
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000646 get() get an entry without an error for a wrong key
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000647 len() number of entries in a Dictionary
648 has_key() check whether a key appears in a Dictionary
649 empty() check if Dictionary is empty
650 remove() remove an entry from a Dictionary
651 extend() add entries from one Dictionary to another
652 filter() remove selected entries from a Dictionary
653 map() change each Dictionary entry
654 keys() get List of Dictionary keys
655 values() get List of Dictionary values
656 items() get List of Dictionary key-value pairs
657 copy() make a shallow copy of a Dictionary
658 deepcopy() make a full copy of a Dictionary
659 string() String representation of a Dictionary
660 max() maximum value in a Dictionary
661 min() minimum value in a Dictionary
662 count() count number of times a value appears
663
Bram Moolenaara3f41662010-07-11 19:01:06 +0200664Floating point computation: *float-functions*
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000665 float2nr() convert Float to Number
666 abs() absolute value (also works for Number)
667 round() round off
668 ceil() round up
669 floor() round down
670 trunc() remove value after decimal point
Bram Moolenaar8d043172014-01-23 14:24:41 +0100671 fmod() remainder of division
672 exp() exponential
673 log() natural logarithm (logarithm to base e)
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000674 log10() logarithm to base 10
675 pow() value of x to the exponent y
676 sqrt() square root
677 sin() sine
678 cos() cosine
Bram Moolenaar662db672011-03-22 14:05:35 +0100679 tan() tangent
680 asin() arc sine
681 acos() arc cosine
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000682 atan() arc tangent
Bram Moolenaar662db672011-03-22 14:05:35 +0100683 atan2() arc tangent
684 sinh() hyperbolic sine
685 cosh() hyperbolic cosine
686 tanh() hyperbolic tangent
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200687 isnan() check for not a number
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000688
Bram Moolenaarb6b046b2011-12-30 13:11:27 +0100689Other computation: *bitwise-function*
690 and() bitwise AND
691 invert() bitwise invert
692 or() bitwise OR
693 xor() bitwise XOR
Bram Moolenaar8d043172014-01-23 14:24:41 +0100694 sha256() SHA-256 hash
Bram Moolenaarb6b046b2011-12-30 13:11:27 +0100695
Bram Moolenaara3f41662010-07-11 19:01:06 +0200696Variables: *var-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000697 type() type of a variable
698 islocked() check if a variable is locked
Bram Moolenaar214641f2017-03-05 17:04:09 +0100699 funcref() get a Funcref for a function reference
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000700 function() get a Funcref for a function name
701 getbufvar() get a variable value from a specific buffer
702 setbufvar() set a variable in a specific buffer
Bram Moolenaarc6249bb2006-04-15 20:25:09 +0000703 getwinvar() get a variable from specific window
Bram Moolenaar06b5d512010-05-22 15:37:44 +0200704 gettabvar() get a variable from specific tab page
Bram Moolenaarc6249bb2006-04-15 20:25:09 +0000705 gettabwinvar() get a variable from specific window & tab page
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000706 setwinvar() set a variable in a specific window
Bram Moolenaar06b5d512010-05-22 15:37:44 +0200707 settabvar() set a variable in a specific tab page
Bram Moolenaarc6249bb2006-04-15 20:25:09 +0000708 settabwinvar() set a variable in a specific window & tab page
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000709 garbagecollect() possibly free memory
710
Bram Moolenaara3f41662010-07-11 19:01:06 +0200711Cursor and mark position: *cursor-functions* *mark-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000712 col() column number of the cursor or a mark
713 virtcol() screen column of the cursor or a mark
714 line() line number of the cursor or mark
715 wincol() window column number of the cursor
716 winline() window line number of the cursor
717 cursor() position the cursor at a line/column
Bram Moolenaar8d043172014-01-23 14:24:41 +0100718 screencol() get screen column of the cursor
719 screenrow() get screen row of the cursor
Bram Moolenaar822ff862014-06-12 21:46:14 +0200720 getcurpos() get position of the cursor
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000721 getpos() get position of cursor, mark, etc.
722 setpos() set position of cursor, mark, etc.
723 byte2line() get line number at a specific byte count
724 line2byte() byte count at a specific line
725 diff_filler() get the number of filler lines above a line
Bram Moolenaar8d043172014-01-23 14:24:41 +0100726 screenattr() get attribute at a screen line/row
727 screenchar() get character code at a screen line/row
Bram Moolenaar2912abb2019-03-29 14:16:42 +0100728 screenchars() get character codes at a screen line/row
729 screenstring() get string of characters at a screen line/row
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000730
Bram Moolenaara3f41662010-07-11 19:01:06 +0200731Working with text in the current buffer: *text-functions*
Bram Moolenaar7c626922005-02-07 22:01:03 +0000732 getline() get a line or list of lines from the buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +0000733 setline() replace a line in the buffer
Bram Moolenaar7c626922005-02-07 22:01:03 +0000734 append() append line or list of lines in the buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +0000735 indent() indent of a specific line
736 cindent() indent according to C indenting
737 lispindent() indent according to Lisp indenting
738 nextnonblank() find next non-blank line
739 prevnonblank() find previous non-blank line
740 search() find a match for a pattern
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000741 searchpos() find a match for a pattern
Bram Moolenaar071d4272004-06-13 20:20:40 +0000742 searchpair() find the other end of a start/skip/end
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000743 searchpairpos() find the other end of a start/skip/end
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000744 searchdecl() search for the declaration of a name
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200745 getcharsearch() return character search information
746 setcharsearch() set character search information
Bram Moolenaar071d4272004-06-13 20:20:40 +0000747
Bram Moolenaara3f41662010-07-11 19:01:06 +0200748 *system-functions* *file-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000749System functions and manipulation of files:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000750 glob() expand wildcards
751 globpath() expand wildcards in a number of directories
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200752 glob2regpat() convert a glob pattern into a search pattern
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000753 findfile() find a file in a list of directories
754 finddir() find a directory in a list of directories
Bram Moolenaar071d4272004-06-13 20:20:40 +0000755 resolve() find out where a shortcut points to
756 fnamemodify() modify a file name
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000757 pathshorten() shorten directory names in a path
758 simplify() simplify a path without changing its meaning
Bram Moolenaar071d4272004-06-13 20:20:40 +0000759 executable() check if an executable program exists
Bram Moolenaar7e38ea22014-04-05 22:55:53 +0200760 exepath() full path of an executable program
Bram Moolenaar071d4272004-06-13 20:20:40 +0000761 filereadable() check if a file can be read
762 filewritable() check if a file can be written to
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000763 getfperm() get the permissions of a file
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200764 setfperm() set the permissions of a file
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000765 getftype() get the kind of a file
Bram Moolenaar071d4272004-06-13 20:20:40 +0000766 isdirectory() check if a directory exists
Bram Moolenaar071d4272004-06-13 20:20:40 +0000767 getfsize() get the size of a file
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000768 getcwd() get the current working directory
Bram Moolenaar00aa0692019-04-27 20:37:57 +0200769 haslocaldir() check if current window used |:lcd| or |:tcd|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000770 tempname() get the name of a temporary file
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000771 mkdir() create a new directory
Bram Moolenaar071d4272004-06-13 20:20:40 +0000772 delete() delete a file
773 rename() rename a file
Bram Moolenaar7e38ea22014-04-05 22:55:53 +0200774 system() get the result of a shell command as a string
775 systemlist() get the result of a shell command as a list
Bram Moolenaar071d4272004-06-13 20:20:40 +0000776 hostname() name of the system
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +0000777 readfile() read a file into a List of lines
Bram Moolenaar62e1bb42019-04-08 16:25:07 +0200778 readdir() get a List of file names in a directory
Bram Moolenaar314dd792019-02-03 15:27:20 +0100779 writefile() write a List of lines or Blob into a file
Bram Moolenaar071d4272004-06-13 20:20:40 +0000780
Bram Moolenaara3f41662010-07-11 19:01:06 +0200781Date and Time: *date-functions* *time-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000782 getftime() get last modification time of a file
783 localtime() get current time in seconds
784 strftime() convert time to a string
785 reltime() get the current or elapsed time accurately
786 reltimestr() convert reltime() result to a string
Bram Moolenaar03413f42016-04-12 21:07:15 +0200787 reltimefloat() convert reltime() result to a Float
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000788
Bram Moolenaara3f41662010-07-11 19:01:06 +0200789 *buffer-functions* *window-functions* *arg-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000790Buffers, windows and the argument list:
791 argc() number of entries in the argument list
792 argidx() current position in the argument list
Bram Moolenaar2d1fe052014-05-28 18:22:57 +0200793 arglistid() get id of the argument list
Bram Moolenaar071d4272004-06-13 20:20:40 +0000794 argv() get one entry from the argument list
795 bufexists() check if a buffer exists
796 buflisted() check if a buffer exists and is listed
797 bufloaded() check if a buffer exists and is loaded
798 bufname() get the name of a specific buffer
799 bufnr() get the buffer number of a specific buffer
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000800 tabpagebuflist() return List of buffers in a tab page
801 tabpagenr() get the number of a tab page
802 tabpagewinnr() like winnr() for a specified tab page
Bram Moolenaar071d4272004-06-13 20:20:40 +0000803 winnr() get the window number for the current window
Bram Moolenaar82af8712016-06-04 20:20:29 +0200804 bufwinid() get the window ID of a specific buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +0000805 bufwinnr() get the window number of a specific buffer
806 winbufnr() get the buffer number of a specific window
Bram Moolenaara3ffd9c2005-07-21 21:03:15 +0000807 getbufline() get a list of lines from the specified buffer
Bram Moolenaarb730f0c2018-11-25 03:56:26 +0100808 setbufline() replace a line in the specified buffer
809 appendbufline() append a list of lines in the specified buffer
810 deletebufline() delete lines from a specified buffer
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200811 win_findbuf() find windows containing a buffer
812 win_getid() get window ID of a window
813 win_gotoid() go to window with ID
814 win_id2tabwin() get tab and window nr from window ID
815 win_id2win() get window nr from window ID
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +0200816 getbufinfo() get a list with buffer information
817 gettabinfo() get a list with tab page information
818 getwininfo() get a list with window information
Bram Moolenaar07ad8162018-02-13 13:59:59 +0100819 getchangelist() get a list of change list entries
Bram Moolenaar4f505882018-02-10 21:06:32 +0100820 getjumplist() get a list of jump list entries
Bram Moolenaarfc65cab2018-08-28 22:58:02 +0200821 swapinfo() information about a swap file
Bram Moolenaarb730f0c2018-11-25 03:56:26 +0100822 swapname() get the swap file path of a buffer
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000823
Bram Moolenaara3f41662010-07-11 19:01:06 +0200824Command line: *command-line-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000825 getcmdline() get the current command line
826 getcmdpos() get position of the cursor in the command line
827 setcmdpos() set position of the cursor in the command line
828 getcmdtype() return the current command-line type
Bram Moolenaarfb539272014-08-22 19:21:47 +0200829 getcmdwintype() return the current command-line window type
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +0200830 getcompletion() list of command-line completion matches
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000831
Bram Moolenaara3f41662010-07-11 19:01:06 +0200832Quickfix and location lists: *quickfix-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000833 getqflist() list of quickfix errors
834 setqflist() modify a quickfix list
835 getloclist() list of location list items
836 setloclist() modify a location list
837
Bram Moolenaara3f41662010-07-11 19:01:06 +0200838Insert mode completion: *completion-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000839 complete() set found matches
840 complete_add() add to found matches
841 complete_check() check if completion should be aborted
Bram Moolenaarfd133322019-03-29 12:20:27 +0100842 complete_info() get current completion information
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000843 pumvisible() check if the popup menu is displayed
Bram Moolenaar071d4272004-06-13 20:20:40 +0000844
Bram Moolenaara3f41662010-07-11 19:01:06 +0200845Folding: *folding-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000846 foldclosed() check for a closed fold at a specific line
847 foldclosedend() like foldclosed() but return the last line
848 foldlevel() check for the fold level at a specific line
849 foldtext() generate the line displayed for a closed fold
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000850 foldtextresult() get the text displayed for a closed fold
Bram Moolenaar071d4272004-06-13 20:20:40 +0000851
Bram Moolenaara3f41662010-07-11 19:01:06 +0200852Syntax and highlighting: *syntax-functions* *highlighting-functions*
Bram Moolenaar6ee10162007-07-26 20:58:42 +0000853 clearmatches() clear all matches defined by |matchadd()| and
854 the |:match| commands
855 getmatches() get all matches defined by |matchadd()| and
856 the |:match| commands
Bram Moolenaar071d4272004-06-13 20:20:40 +0000857 hlexists() check if a highlight group exists
858 hlID() get ID of a highlight group
859 synID() get syntax ID at a specific position
860 synIDattr() get a specific attribute of a syntax ID
861 synIDtrans() get translated syntax ID
Bram Moolenaar166af9b2010-11-16 20:34:40 +0100862 synstack() get list of syntax IDs at a specific position
Bram Moolenaar81af9252010-12-10 20:35:50 +0100863 synconcealed() get info about concealing
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000864 diff_hlID() get highlight ID for diff mode at a position
Bram Moolenaar6ee10162007-07-26 20:58:42 +0000865 matchadd() define a pattern to highlight (a "match")
Bram Moolenaarb3414592014-06-17 17:48:32 +0200866 matchaddpos() define a list of positions to highlight
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000867 matcharg() get info about |:match| arguments
Bram Moolenaar6ee10162007-07-26 20:58:42 +0000868 matchdelete() delete a match defined by |matchadd()| or a
869 |:match| command
870 setmatches() restore a list of matches saved by
871 |getmatches()|
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000872
Bram Moolenaara3f41662010-07-11 19:01:06 +0200873Spelling: *spell-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000874 spellbadword() locate badly spelled word at or after cursor
875 spellsuggest() return suggested spelling corrections
876 soundfold() return the sound-a-like equivalent of a word
Bram Moolenaar071d4272004-06-13 20:20:40 +0000877
Bram Moolenaara3f41662010-07-11 19:01:06 +0200878History: *history-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000879 histadd() add an item to a history
880 histdel() delete an item from a history
881 histget() get an item from a history
882 histnr() get highest index of a history list
883
Bram Moolenaara3f41662010-07-11 19:01:06 +0200884Interactive: *interactive-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000885 browse() put up a file requester
886 browsedir() put up a directory requester
Bram Moolenaar071d4272004-06-13 20:20:40 +0000887 confirm() let the user make a choice
888 getchar() get a character from the user
889 getcharmod() get modifiers for the last typed character
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000890 feedkeys() put characters in the typeahead queue
Bram Moolenaar071d4272004-06-13 20:20:40 +0000891 input() get a line from the user
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000892 inputlist() let the user pick an entry from a list
Bram Moolenaar071d4272004-06-13 20:20:40 +0000893 inputsecret() get a line from the user without showing it
894 inputdialog() get a line from the user in a dialog
Bram Moolenaar68b76a62005-03-25 21:53:48 +0000895 inputsave() save and clear typeahead
Bram Moolenaar071d4272004-06-13 20:20:40 +0000896 inputrestore() restore typeahead
897
Bram Moolenaara3f41662010-07-11 19:01:06 +0200898GUI: *gui-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000899 getfontname() get name of current font being used
Bram Moolenaarb5b75622018-03-09 22:22:21 +0100900 getwinpos() position of the Vim window
901 getwinposx() X position of the Vim window
902 getwinposy() Y position of the Vim window
Bram Moolenaar214641f2017-03-05 17:04:09 +0100903 balloon_show() set the balloon content
Bram Moolenaara2a80162017-11-21 23:09:50 +0100904 balloon_split() split a message for a balloon
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000905
Bram Moolenaara3f41662010-07-11 19:01:06 +0200906Vim server: *server-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000907 serverlist() return the list of server names
Bram Moolenaar01164a62017-11-02 22:58:42 +0100908 remote_startserver() run a server
Bram Moolenaar071d4272004-06-13 20:20:40 +0000909 remote_send() send command characters to a Vim server
910 remote_expr() evaluate an expression in a Vim server
911 server2client() send a reply to a client of a Vim server
912 remote_peek() check if there is a reply from a Vim server
913 remote_read() read a reply from a Vim server
914 foreground() move the Vim window to the foreground
915 remote_foreground() move the Vim server window to the foreground
916
Bram Moolenaara3f41662010-07-11 19:01:06 +0200917Window size and position: *window-size-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000918 winheight() get height of a specific window
919 winwidth() get width of a specific window
Bram Moolenaarf0b03c42017-12-17 17:17:07 +0100920 win_screenpos() get screen position of a window
Bram Moolenaarb730f0c2018-11-25 03:56:26 +0100921 winlayout() get layout of windows in a tab page
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000922 winrestcmd() return command to restore window sizes
923 winsaveview() get view of current window
924 winrestview() restore saved view of current window
925
Bram Moolenaar26402cb2013-02-20 21:26:00 +0100926Mappings: *mapping-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000927 hasmapto() check if a mapping exists
928 mapcheck() check if a matching mapping exists
929 maparg() get rhs of a mapping
Bram Moolenaar26402cb2013-02-20 21:26:00 +0100930 wildmenumode() check if the wildmode is active
931
Bram Moolenaar683fa182015-11-30 21:38:24 +0100932Testing: *test-functions*
Bram Moolenaare18c0b32016-03-20 21:08:34 +0100933 assert_equal() assert that two expressions values are equal
Bram Moolenaarb730f0c2018-11-25 03:56:26 +0100934 assert_equalfile() assert that two file contents are equal
Bram Moolenaar03413f42016-04-12 21:07:15 +0200935 assert_notequal() assert that two expressions values are not equal
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +0200936 assert_inrange() assert that an expression is inside a range
Bram Moolenaar7db8f6f2016-03-29 23:12:46 +0200937 assert_match() assert that a pattern matches the value
Bram Moolenaar03413f42016-04-12 21:07:15 +0200938 assert_notmatch() assert that a pattern does not match the value
Bram Moolenaar683fa182015-11-30 21:38:24 +0100939 assert_false() assert that an expression is false
940 assert_true() assert that an expression is true
Bram Moolenaare18c0b32016-03-20 21:08:34 +0100941 assert_exception() assert that a command throws an exception
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +0100942 assert_beeps() assert that a command beeps
943 assert_fails() assert that a command fails
Bram Moolenaar3c2881d2017-03-21 19:18:29 +0100944 assert_report() report a test failure
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200945 test_alloc_fail() make memory allocation fail
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +0200946 test_autochdir() enable 'autochdir' during startup
Bram Moolenaar036986f2017-03-16 17:41:02 +0100947 test_override() test with Vim internal overrides
948 test_garbagecollect_now() free memory right now
Bram Moolenaar214641f2017-03-05 17:04:09 +0100949 test_ignore_error() ignore a specific error message
Bram Moolenaar314dd792019-02-03 15:27:20 +0100950 test_null_blob() return a null Blob
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200951 test_null_channel() return a null Channel
952 test_null_dict() return a null Dict
953 test_null_job() return a null Job
954 test_null_list() return a null List
955 test_null_partial() return a null Partial function
956 test_null_string() return a null String
Bram Moolenaar214641f2017-03-05 17:04:09 +0100957 test_settime() set the time Vim uses internally
Bram Moolenaarbb8476b2019-05-04 15:47:48 +0200958 test_setmouse() set the mouse position
Bram Moolenaarb730f0c2018-11-25 03:56:26 +0100959 test_feedinput() add key sequence to input buffer
960 test_option_not_set() reset flag indicating option was set
961 test_scrollbar() simulate scrollbar movement in the GUI
Bram Moolenaar683fa182015-11-30 21:38:24 +0100962
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200963Inter-process communication: *channel-functions*
Bram Moolenaar51628222016-12-01 23:03:28 +0100964 ch_canread() check if there is something to read
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100965 ch_open() open a channel
966 ch_close() close a channel
Bram Moolenaar64d8e252016-09-06 22:12:34 +0200967 ch_close_in() close the in part of a channel
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200968 ch_read() read a message from a channel
Bram Moolenaard09091d2019-01-17 16:07:22 +0100969 ch_readblob() read a Blob from a channel
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200970 ch_readraw() read a raw message from a channel
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100971 ch_sendexpr() send a JSON message over a channel
972 ch_sendraw() send a raw message over a channel
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200973 ch_evalexpr() evaluates an expression over channel
974 ch_evalraw() evaluates a raw string over channel
975 ch_status() get status of a channel
976 ch_getbufnr() get the buffer number of a channel
977 ch_getjob() get the job associated with a channel
978 ch_info() get channel information
979 ch_log() write a message in the channel log file
980 ch_logfile() set the channel log file
981 ch_setoptions() set the options for a channel
Bram Moolenaara02a5512016-06-17 12:48:11 +0200982 json_encode() encode an expression to a JSON string
983 json_decode() decode a JSON string to Vim types
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200984 js_encode() encode an expression to a JSON string
985 js_decode() decode a JSON string to Vim types
986
987Jobs: *job-functions*
988 job_start() start a job
989 job_stop() stop a job
990 job_status() get the status of a job
991 job_getchannel() get the channel used by a job
992 job_info() get information about a job
993 job_setoptions() set options for a job
994
Bram Moolenaar162b7142018-12-21 15:17:36 +0100995Signs: *sign-functions*
996 sign_define() define or update a sign
997 sign_getdefined() get a list of defined signs
998 sign_getplaced() get a list of placed signs
Bram Moolenaar6b7b7192019-01-11 13:42:41 +0100999 sign_jump() jump to a sign
Bram Moolenaar162b7142018-12-21 15:17:36 +01001000 sign_place() place a sign
1001 sign_undefine() undefine a sign
1002 sign_unplace() unplace a sign
1003
Bram Moolenaarc572da52017-08-27 16:52:01 +02001004Terminal window: *terminal-functions*
1005 term_start() open a terminal window and run a job
1006 term_list() get the list of terminal buffers
1007 term_sendkeys() send keystrokes to a terminal
1008 term_wait() wait for screen to be updated
1009 term_getjob() get the job associated with a terminal
1010 term_scrape() get row of a terminal screen
1011 term_getline() get a line of text from a terminal
1012 term_getattr() get the value of attribute {what}
1013 term_getcursor() get the cursor position of a terminal
1014 term_getscrolled() get the scroll count of a terminal
1015 term_getaltscreen() get the alternate screen flag
1016 term_getsize() get the size of a terminal
1017 term_getstatus() get the status of a terminal
1018 term_gettitle() get the title of a terminal
1019 term_gettty() get the tty name of a terminal
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02001020 term_setansicolors() set 16 ANSI colors, used for GUI
1021 term_getansicolors() get 16 ANSI colors, used for GUI
Bram Moolenaarb730f0c2018-11-25 03:56:26 +01001022 term_dumpdiff() display difference between two screen dumps
1023 term_dumpload() load a terminal screen dump in a window
1024 term_dumpwrite() dump contents of a terminal screen to a file
1025 term_setkill() set signal to stop job in a terminal
1026 term_setrestore() set command to restore a terminal
1027 term_setsize() set the size of a terminal
Bram Moolenaarc572da52017-08-27 16:52:01 +02001028
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001029Timers: *timer-functions*
1030 timer_start() create a timer
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02001031 timer_pause() pause or unpause a timer
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001032 timer_stop() stop a timer
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02001033 timer_stopall() stop all timers
1034 timer_info() get information about timers
Bram Moolenaar298b4402016-01-28 22:38:53 +01001035
Bram Moolenaarb730f0c2018-11-25 03:56:26 +01001036Tags: *tag-functions*
1037 taglist() get list of matching tags
1038 tagfiles() get a list of tags files
1039 gettagstack() get the tag stack of a window
1040 settagstack() modify the tag stack of a window
1041
1042Prompt Buffer: *promptbuffer-functions*
1043 prompt_setcallback() set prompt callback for a buffer
1044 prompt_setinterrupt() set interrupt callback for a buffer
1045 prompt_setprompt() set the prompt text for a buffer
1046
Bram Moolenaar26402cb2013-02-20 21:26:00 +01001047Various: *various-functions*
1048 mode() get current editing mode
1049 visualmode() last visual mode used
Bram Moolenaar071d4272004-06-13 20:20:40 +00001050 exists() check if a variable, function, etc. exists
1051 has() check if a feature is supported in Vim
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001052 changenr() return number of most recent change
Bram Moolenaar071d4272004-06-13 20:20:40 +00001053 cscope_connection() check if a cscope connection exists
1054 did_filetype() check if a FileType autocommand was used
1055 eventhandler() check if invoked by an event handler
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00001056 getpid() get process ID of Vim
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001057
Bram Moolenaar071d4272004-06-13 20:20:40 +00001058 libcall() call a function in an external library
1059 libcallnr() idem, returning a number
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001060
Bram Moolenaar8d043172014-01-23 14:24:41 +01001061 undofile() get the name of the undo file
1062 undotree() return the state of the undo tree
1063
Bram Moolenaar071d4272004-06-13 20:20:40 +00001064 getreg() get contents of a register
1065 getregtype() get type of a register
1066 setreg() set contents and type of a register
Bram Moolenaar0b6d9112018-05-22 20:35:17 +02001067 reg_executing() return the name of the register being executed
1068 reg_recording() return the name of the register being recorded
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001069
Bram Moolenaar8d043172014-01-23 14:24:41 +01001070 shiftwidth() effective value of 'shiftwidth'
1071
Bram Moolenaar063b9d12016-07-09 20:21:48 +02001072 wordcount() get byte/word/char count of buffer
1073
Bram Moolenaar8d043172014-01-23 14:24:41 +01001074 luaeval() evaluate Lua expression
Bram Moolenaar7e506b62010-01-19 15:55:06 +01001075 mzeval() evaluate |MzScheme| expression
Bram Moolenaare9b892e2016-01-17 21:15:58 +01001076 perleval() evaluate Perl expression (|+perl|)
Bram Moolenaar8d043172014-01-23 14:24:41 +01001077 py3eval() evaluate Python expression (|+python3|)
1078 pyeval() evaluate Python expression (|+python|)
Bram Moolenaar690afe12017-01-28 18:34:47 +01001079 pyxeval() evaluate |python_x| expression
Bram Moolenaar9d87a372018-12-18 21:41:50 +01001080 debugbreak() interrupt a program being debugged
Bram Moolenaar7e506b62010-01-19 15:55:06 +01001081
Bram Moolenaar071d4272004-06-13 20:20:40 +00001082==============================================================================
1083*41.7* Defining a function
1084
1085Vim enables you to define your own functions. The basic function declaration
1086begins as follows: >
1087
1088 :function {name}({var1}, {var2}, ...)
1089 : {body}
1090 :endfunction
1091<
1092 Note:
1093 Function names must begin with a capital letter.
1094
1095Let's define a short function to return the smaller of two numbers. It starts
1096with this line: >
1097
1098 :function Min(num1, num2)
1099
1100This tells Vim that the function is named "Min" and it takes two arguments:
1101"num1" and "num2".
1102 The first thing you need to do is to check to see which number is smaller:
1103 >
1104 : if a:num1 < a:num2
1105
1106The special prefix "a:" tells Vim that the variable is a function argument.
1107Let's assign the variable "smaller" the value of the smallest number: >
1108
1109 : if a:num1 < a:num2
1110 : let smaller = a:num1
1111 : else
1112 : let smaller = a:num2
1113 : endif
1114
1115The variable "smaller" is a local variable. Variables used inside a function
1116are local unless prefixed by something like "g:", "a:", or "s:".
1117
1118 Note:
1119 To access a global variable from inside a function you must prepend
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00001120 "g:" to it. Thus "g:today" inside a function is used for the global
1121 variable "today", and "today" is another variable, local to the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001122 function.
1123
1124You now use the ":return" statement to return the smallest number to the user.
1125Finally, you end the function: >
1126
1127 : return smaller
1128 :endfunction
1129
1130The complete function definition is as follows: >
1131
1132 :function Min(num1, num2)
1133 : if a:num1 < a:num2
1134 : let smaller = a:num1
1135 : else
1136 : let smaller = a:num2
1137 : endif
1138 : return smaller
1139 :endfunction
1140
Bram Moolenaar7c626922005-02-07 22:01:03 +00001141For people who like short functions, this does the same thing: >
1142
1143 :function Min(num1, num2)
1144 : if a:num1 < a:num2
1145 : return a:num1
1146 : endif
1147 : return a:num2
1148 :endfunction
1149
Bram Moolenaard1f56e62006-02-22 21:25:37 +00001150A user defined function is called in exactly the same way as a built-in
Bram Moolenaar071d4272004-06-13 20:20:40 +00001151function. Only the name is different. The Min function can be used like
1152this: >
1153
1154 :echo Min(5, 8)
1155
1156Only now will the function be executed and the lines be interpreted by Vim.
1157If there are mistakes, like using an undefined variable or function, you will
1158now get an error message. When defining the function these errors are not
1159detected.
1160
1161When a function reaches ":endfunction" or ":return" is used without an
1162argument, the function returns zero.
1163
1164To redefine a function that already exists, use the ! for the ":function"
1165command: >
1166
1167 :function! Min(num1, num2, num3)
1168
1169
1170USING A RANGE
1171
1172The ":call" command can be given a line range. This can have one of two
1173meanings. When a function has been defined with the "range" keyword, it will
1174take care of the line range itself.
1175 The function will be passed the variables "a:firstline" and "a:lastline".
1176These will have the line numbers from the range the function was called with.
1177Example: >
1178
1179 :function Count_words() range
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00001180 : let lnum = a:firstline
1181 : let n = 0
1182 : while lnum <= a:lastline
1183 : let n = n + len(split(getline(lnum)))
1184 : let lnum = lnum + 1
Bram Moolenaar071d4272004-06-13 20:20:40 +00001185 : endwhile
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00001186 : echo "found " . n . " words"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001187 :endfunction
1188
1189You can call this function with: >
1190
1191 :10,30call Count_words()
1192
1193It will be executed once and echo the number of words.
1194 The other way to use a line range is by defining a function without the
1195"range" keyword. The function will be called once for every line in the
1196range, with the cursor in that line. Example: >
1197
1198 :function Number()
1199 : echo "line " . line(".") . " contains: " . getline(".")
1200 :endfunction
1201
1202If you call this function with: >
1203
1204 :10,15call Number()
1205
1206The function will be called six times.
1207
1208
1209VARIABLE NUMBER OF ARGUMENTS
1210
1211Vim enables you to define functions that have a variable number of arguments.
1212The following command, for instance, defines a function that must have 1
1213argument (start) and can have up to 20 additional arguments: >
1214
1215 :function Show(start, ...)
1216
1217The variable "a:1" contains the first optional argument, "a:2" the second, and
1218so on. The variable "a:0" contains the number of extra arguments.
1219 For example: >
1220
1221 :function Show(start, ...)
1222 : echohl Title
Bram Moolenaar00654022011-02-25 14:42:19 +01001223 : echo "start is " . a:start
Bram Moolenaar071d4272004-06-13 20:20:40 +00001224 : echohl None
1225 : let index = 1
1226 : while index <= a:0
1227 : echo " Arg " . index . " is " . a:{index}
1228 : let index = index + 1
1229 : endwhile
1230 : echo ""
1231 :endfunction
1232
1233This uses the ":echohl" command to specify the highlighting used for the
1234following ":echo" command. ":echohl None" stops it again. The ":echon"
1235command works like ":echo", but doesn't output a line break.
1236
Bram Moolenaar7c626922005-02-07 22:01:03 +00001237You can also use the a:000 variable, it is a List of all the "..." arguments.
1238See |a:000|.
1239
Bram Moolenaar071d4272004-06-13 20:20:40 +00001240
1241LISTING FUNCTIONS
1242
1243The ":function" command lists the names and arguments of all user-defined
1244functions: >
1245
1246 :function
1247< function Show(start, ...) ~
1248 function GetVimIndent() ~
1249 function SetSyn(name) ~
1250
1251To see what a function does, use its name as an argument for ":function": >
1252
1253 :function SetSyn
1254< 1 if &syntax == '' ~
1255 2 let &syntax = a:name ~
1256 3 endif ~
1257 endfunction ~
1258
1259
1260DEBUGGING
1261
1262The line number is useful for when you get an error message or when debugging.
1263See |debug-scripts| about debugging mode.
1264 You can also set the 'verbose' option to 12 or higher to see all function
1265calls. Set it to 15 or higher to see every executed line.
1266
1267
1268DELETING A FUNCTION
1269
1270To delete the Show() function: >
1271
1272 :delfunction Show
1273
1274You get an error when the function doesn't exist.
1275
Bram Moolenaar7c626922005-02-07 22:01:03 +00001276
1277FUNCTION REFERENCES
1278
1279Sometimes it can be useful to have a variable point to one function or
1280another. You can do it with the function() function. It turns the name of a
1281function into a reference: >
1282
1283 :let result = 0 " or 1
1284 :function! Right()
1285 : return 'Right!'
1286 :endfunc
1287 :function! Wrong()
1288 : return 'Wrong!'
1289 :endfunc
1290 :
1291 :if result == 1
1292 : let Afunc = function('Right')
1293 :else
1294 : let Afunc = function('Wrong')
1295 :endif
1296 :echo call(Afunc, [])
1297< Wrong! ~
1298
1299Note that the name of a variable that holds a function reference must start
1300with a capital. Otherwise it could be confused with the name of a builtin
1301function.
1302 The way to invoke a function that a variable refers to is with the call()
1303function. Its first argument is the function reference, the second argument
1304is a List with arguments.
1305
1306Function references are most useful in combination with a Dictionary, as is
1307explained in the next section.
1308
Bram Moolenaar071d4272004-06-13 20:20:40 +00001309==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00001310*41.8* Lists and Dictionaries
1311
1312So far we have used the basic types String and Number. Vim also supports two
1313composite types: List and Dictionary.
1314
1315A List is an ordered sequence of things. The things can be any kind of value,
1316thus you can make a List of numbers, a List of Lists and even a List of mixed
1317items. To create a List with three strings: >
1318
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001319 :let alist = ['aap', 'mies', 'noot']
Bram Moolenaar7c626922005-02-07 22:01:03 +00001320
1321The List items are enclosed in square brackets and separated by commas. To
1322create an empty List: >
1323
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001324 :let alist = []
Bram Moolenaar7c626922005-02-07 22:01:03 +00001325
1326You can add items to a List with the add() function: >
1327
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001328 :let alist = []
Bram Moolenaar7c626922005-02-07 22:01:03 +00001329 :call add(alist, 'foo')
1330 :call add(alist, 'bar')
1331 :echo alist
1332< ['foo', 'bar'] ~
1333
1334List concatenation is done with +: >
1335
1336 :echo alist + ['foo', 'bar']
1337< ['foo', 'bar', 'foo', 'bar'] ~
1338
1339Or, if you want to extend a List directly: >
1340
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001341 :let alist = ['one']
Bram Moolenaar7c626922005-02-07 22:01:03 +00001342 :call extend(alist, ['two', 'three'])
1343 :echo alist
1344< ['one', 'two', 'three'] ~
1345
1346Notice that using add() will have a different effect: >
1347
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001348 :let alist = ['one']
Bram Moolenaar7c626922005-02-07 22:01:03 +00001349 :call add(alist, ['two', 'three'])
1350 :echo alist
1351< ['one', ['two', 'three']] ~
1352
1353The second argument of add() is added as a single item.
1354
1355
1356FOR LOOP
1357
1358One of the nice things you can do with a List is iterate over it: >
1359
1360 :let alist = ['one', 'two', 'three']
1361 :for n in alist
1362 : echo n
1363 :endfor
1364< one ~
1365 two ~
1366 three ~
1367
1368This will loop over each element in List "alist", assigning the value to
1369variable "n". The generic form of a for loop is: >
1370
1371 :for {varname} in {listexpression}
1372 : {commands}
1373 :endfor
1374
1375To loop a certain number of times you need a List of a specific length. The
1376range() function creates one for you: >
1377
1378 :for a in range(3)
1379 : echo a
1380 :endfor
1381< 0 ~
1382 1 ~
1383 2 ~
1384
1385Notice that the first item of the List that range() produces is zero, thus the
1386last item is one less than the length of the list.
1387 You can also specify the maximum value, the stride and even go backwards: >
1388
1389 :for a in range(8, 4, -2)
1390 : echo a
1391 :endfor
1392< 8 ~
1393 6 ~
1394 4 ~
1395
1396A more useful example, looping over lines in the buffer: >
1397
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001398 :for line in getline(1, 20)
1399 : if line =~ "Date: "
1400 : echo matchstr(line, 'Date: \zs.*')
1401 : endif
1402 :endfor
Bram Moolenaar7c626922005-02-07 22:01:03 +00001403
1404This looks into lines 1 to 20 (inclusive) and echoes any date found in there.
1405
1406
1407DICTIONARIES
1408
1409A Dictionary stores key-value pairs. You can quickly lookup a value if you
1410know the key. A Dictionary is created with curly braces: >
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001411
Bram Moolenaar7c626922005-02-07 22:01:03 +00001412 :let uk2nl = {'one': 'een', 'two': 'twee', 'three': 'drie'}
1413
Bram Moolenaar4399ef42005-02-12 14:29:27 +00001414Now you can lookup words by putting the key in square brackets: >
Bram Moolenaar7c626922005-02-07 22:01:03 +00001415
1416 :echo uk2nl['two']
1417< twee ~
1418
1419The generic form for defining a Dictionary is: >
1420
1421 {<key> : <value>, ...}
1422
1423An empty Dictionary is one without any keys: >
1424
1425 {}
1426
1427The possibilities with Dictionaries are numerous. There are various functions
1428for them as well. For example, you can obtain a list of the keys and loop
1429over them: >
1430
1431 :for key in keys(uk2nl)
1432 : echo key
1433 :endfor
1434< three ~
1435 one ~
1436 two ~
1437
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00001438You will notice the keys are not ordered. You can sort the list to get a
Bram Moolenaar7c626922005-02-07 22:01:03 +00001439specific order: >
1440
1441 :for key in sort(keys(uk2nl))
1442 : echo key
1443 :endfor
1444< one ~
1445 three ~
1446 two ~
1447
1448But you can never get back the order in which items are defined. For that you
1449need to use a List, it stores items in an ordered sequence.
1450
1451
1452DICTIONARY FUNCTIONS
1453
1454The items in a Dictionary can normally be obtained with an index in square
1455brackets: >
1456
1457 :echo uk2nl['one']
1458< een ~
1459
1460A method that does the same, but without so many punctuation characters: >
1461
1462 :echo uk2nl.one
1463< een ~
1464
1465This only works for a key that is made of ASCII letters, digits and the
1466underscore. You can also assign a new value this way: >
1467
1468 :let uk2nl.four = 'vier'
1469 :echo uk2nl
1470< {'three': 'drie', 'four': 'vier', 'one': 'een', 'two': 'twee'} ~
1471
1472And now for something special: you can directly define a function and store a
1473reference to it in the dictionary: >
1474
1475 :function uk2nl.translate(line) dict
1476 : return join(map(split(a:line), 'get(self, v:val, "???")'))
1477 :endfunction
1478
1479Let's first try it out: >
1480
1481 :echo uk2nl.translate('three two five one')
1482< drie twee ??? een ~
1483
1484The first special thing you notice is the "dict" at the end of the ":function"
1485line. This marks the function as being used from a Dictionary. The "self"
1486local variable will then refer to that Dictionary.
1487 Now let's break up the complicated return command: >
1488
1489 split(a:line)
1490
Bram Moolenaar00654022011-02-25 14:42:19 +01001491The split() function takes a string, chops it into whitespace separated words
Bram Moolenaar7c626922005-02-07 22:01:03 +00001492and returns a list with these words. Thus in the example it returns: >
1493
1494 :echo split('three two five one')
1495< ['three', 'two', 'five', 'one'] ~
1496
1497This list is the first argument to the map() function. This will go through
1498the list, evaluating its second argument with "v:val" set to the value of each
1499item. This is a shortcut to using a for loop. This command: >
1500
1501 :let alist = map(split(a:line), 'get(self, v:val, "???")')
1502
1503Is equivalent to: >
1504
1505 :let alist = split(a:line)
1506 :for idx in range(len(alist))
1507 : let alist[idx] = get(self, alist[idx], "???")
1508 :endfor
1509
1510The get() function checks if a key is present in a Dictionary. If it is, then
1511the value is retrieved. If it isn't, then the default value is returned, in
Bram Moolenaar4399ef42005-02-12 14:29:27 +00001512the example it's '???'. This is a convenient way to handle situations where a
Bram Moolenaar7c626922005-02-07 22:01:03 +00001513key may not be present and you don't want an error message.
1514
1515The join() function does the opposite of split(): it joins together a list of
1516words, putting a space in between.
1517 This combination of split(), map() and join() is a nice way to filter a line
1518of words in a very compact way.
1519
1520
1521OBJECT ORIENTED PROGRAMMING
1522
1523Now that you can put both values and functions in a Dictionary, you can
1524actually use a Dictionary like an object.
1525 Above we used a Dictionary for translating Dutch to English. We might want
1526to do the same for other languages. Let's first make an object (aka
1527Dictionary) that has the translate function, but no words to translate: >
1528
1529 :let transdict = {}
1530 :function transdict.translate(line) dict
1531 : return join(map(split(a:line), 'get(self.words, v:val, "???")'))
1532 :endfunction
1533
1534It's slightly different from the function above, using 'self.words' to lookup
1535word translations. But we don't have a self.words. Thus you could call this
1536an abstract class.
1537
1538Now we can instantiate a Dutch translation object: >
1539
1540 :let uk2nl = copy(transdict)
1541 :let uk2nl.words = {'one': 'een', 'two': 'twee', 'three': 'drie'}
1542 :echo uk2nl.translate('three one')
1543< drie een ~
1544
1545And a German translator: >
1546
1547 :let uk2de = copy(transdict)
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001548 :let uk2de.words = {'one': 'eins', 'two': 'zwei', 'three': 'drei'}
Bram Moolenaar7c626922005-02-07 22:01:03 +00001549 :echo uk2de.translate('three one')
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001550< drei eins ~
Bram Moolenaar7c626922005-02-07 22:01:03 +00001551
1552You see that the copy() function is used to make a copy of the "transdict"
1553Dictionary and then the copy is changed to add the words. The original
1554remains the same, of course.
1555
1556Now you can go one step further, and use your preferred translator: >
1557
1558 :if $LANG =~ "de"
1559 : let trans = uk2de
1560 :else
1561 : let trans = uk2nl
1562 :endif
1563 :echo trans.translate('one two three')
1564< een twee drie ~
1565
1566Here "trans" refers to one of the two objects (Dictionaries). No copy is
1567made. More about List and Dictionary identity can be found at |list-identity|
1568and |dict-identity|.
1569
1570Now you might use a language that isn't supported. You can overrule the
1571translate() function to do nothing: >
1572
1573 :let uk2uk = copy(transdict)
1574 :function! uk2uk.translate(line)
1575 : return a:line
1576 :endfunction
1577 :echo uk2uk.translate('three one wladiwostok')
1578< three one wladiwostok ~
1579
1580Notice that a ! was used to overwrite the existing function reference. Now
1581use "uk2uk" when no recognized language is found: >
1582
1583 :if $LANG =~ "de"
1584 : let trans = uk2de
1585 :elseif $LANG =~ "nl"
1586 : let trans = uk2nl
1587 :else
1588 : let trans = uk2uk
1589 :endif
1590 :echo trans.translate('one two three')
1591< one two three ~
1592
1593For further reading see |Lists| and |Dictionaries|.
1594
1595==============================================================================
1596*41.9* Exceptions
Bram Moolenaar071d4272004-06-13 20:20:40 +00001597
1598Let's start with an example: >
1599
1600 :try
1601 : read ~/templates/pascal.tmpl
1602 :catch /E484:/
1603 : echo "Sorry, the Pascal template file cannot be found."
1604 :endtry
1605
1606The ":read" command will fail if the file does not exist. Instead of
1607generating an error message, this code catches the error and gives the user a
Bram Moolenaar00654022011-02-25 14:42:19 +01001608nice message.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001609
1610For the commands in between ":try" and ":endtry" errors are turned into
1611exceptions. An exception is a string. In the case of an error the string
1612contains the error message. And every error message has a number. In this
1613case, the error we catch contains "E484:". This number is guaranteed to stay
1614the same (the text may change, e.g., it may be translated).
1615
1616When the ":read" command causes another error, the pattern "E484:" will not
1617match in it. Thus this exception will not be caught and result in the usual
1618error message.
1619
1620You might be tempted to do this: >
1621
1622 :try
1623 : read ~/templates/pascal.tmpl
1624 :catch
1625 : echo "Sorry, the Pascal template file cannot be found."
1626 :endtry
1627
1628This means all errors are caught. But then you will not see errors that are
1629useful, such as "E21: Cannot make changes, 'modifiable' is off".
1630
1631Another useful mechanism is the ":finally" command: >
1632
1633 :let tmp = tempname()
1634 :try
1635 : exe ".,$write " . tmp
1636 : exe "!filter " . tmp
1637 : .,$delete
1638 : exe "$read " . tmp
1639 :finally
1640 : call delete(tmp)
1641 :endtry
1642
1643This filters the lines from the cursor until the end of the file through the
1644"filter" command, which takes a file name argument. No matter if the
1645filtering works, something goes wrong in between ":try" and ":finally" or the
1646user cancels the filtering by pressing CTRL-C, the "call delete(tmp)" is
1647always executed. This makes sure you don't leave the temporary file behind.
1648
1649More information about exception handling can be found in the reference
1650manual: |exception-handling|.
1651
1652==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00001653*41.10* Various remarks
Bram Moolenaar071d4272004-06-13 20:20:40 +00001654
1655Here is a summary of items that apply to Vim scripts. They are also mentioned
1656elsewhere, but form a nice checklist.
1657
1658The end-of-line character depends on the system. For Unix a single <NL>
1659character is used. For MS-DOS, Windows, OS/2 and the like, <CR><LF> is used.
1660This is important when using mappings that end in a <CR>. See |:source_crnl|.
1661
1662
1663WHITE SPACE
1664
1665Blank lines are allowed and ignored.
1666
1667Leading whitespace characters (blanks and TABs) are always ignored. The
Bram Moolenaar214641f2017-03-05 17:04:09 +01001668whitespaces between parameters (e.g. between the "set" and the "cpoptions" in
Bram Moolenaar071d4272004-06-13 20:20:40 +00001669the example below) are reduced to one blank character and plays the role of a
1670separator, the whitespaces after the last (visible) character may or may not
1671be ignored depending on the situation, see below.
1672
1673For a ":set" command involving the "=" (equal) sign, such as in: >
1674
1675 :set cpoptions =aABceFst
1676
1677the whitespace immediately before the "=" sign is ignored. But there can be
1678no whitespace after the "=" sign!
1679
1680To include a whitespace character in the value of an option, it must be
1681escaped by a "\" (backslash) as in the following example: >
1682
1683 :set tags=my\ nice\ file
1684
Bram Moolenaar00654022011-02-25 14:42:19 +01001685The same example written as: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001686
1687 :set tags=my nice file
1688
1689will issue an error, because it is interpreted as: >
1690
1691 :set tags=my
1692 :set nice
1693 :set file
1694
1695
1696COMMENTS
1697
1698The character " (the double quote mark) starts a comment. Everything after
1699and including this character until the end-of-line is considered a comment and
1700is ignored, except for commands that don't consider comments, as shown in
1701examples below. A comment can start on any character position on the line.
1702
1703There is a little "catch" with comments for some commands. Examples: >
1704
1705 :abbrev dev development " shorthand
1706 :map <F3> o#include " insert include
1707 :execute cmd " do it
1708 :!ls *.c " list C files
1709
1710The abbreviation 'dev' will be expanded to 'development " shorthand'. The
1711mapping of <F3> will actually be the whole line after the 'o# ....' including
1712the '" insert include'. The "execute" command will give an error. The "!"
1713command will send everything after it to the shell, causing an error for an
1714unmatched '"' character.
1715 There can be no comment after ":map", ":abbreviate", ":execute" and "!"
1716commands (there are a few more commands with this restriction). For the
1717":map", ":abbreviate" and ":execute" commands there is a trick: >
1718
1719 :abbrev dev development|" shorthand
1720 :map <F3> o#include|" insert include
1721 :execute cmd |" do it
1722
1723With the '|' character the command is separated from the next one. And that
Bram Moolenaar9e1d2832007-05-06 12:51:41 +00001724next command is only a comment. For the last command you need to do two
1725things: |:execute| and use '|': >
1726 :exe '!ls *.c' |" list C files
Bram Moolenaar071d4272004-06-13 20:20:40 +00001727
1728Notice that there is no white space before the '|' in the abbreviation and
1729mapping. For these commands, any character until the end-of-line or '|' is
1730included. As a consequence of this behavior, you don't always see that
1731trailing whitespace is included: >
1732
1733 :map <F4> o#include
1734
Bram Moolenaar9e1d2832007-05-06 12:51:41 +00001735To spot these problems, you can set the 'list' option when editing vimrc
Bram Moolenaar071d4272004-06-13 20:20:40 +00001736files.
1737
Bram Moolenaar9e1d2832007-05-06 12:51:41 +00001738For Unix there is one special way to comment a line, that allows making a Vim
1739script executable: >
1740 #!/usr/bin/env vim -S
1741 echo "this is a Vim script"
1742 quit
1743
1744The "#" command by itself lists a line with the line number. Adding an
1745exclamation mark changes it into doing nothing, so that you can add the shell
1746command to execute the rest of the file. |:#!| |-S|
1747
Bram Moolenaar071d4272004-06-13 20:20:40 +00001748
1749PITFALLS
1750
1751Even bigger problem arises in the following example: >
1752
1753 :map ,ab o#include
1754 :unmap ,ab
1755
1756Here the unmap command will not work, because it tries to unmap ",ab ". This
1757does not exist as a mapped sequence. An error will be issued, which is very
1758hard to identify, because the ending whitespace character in ":unmap ,ab " is
1759not visible.
1760
1761And this is the same as what happens when one uses a comment after an 'unmap'
1762command: >
1763
1764 :unmap ,ab " comment
1765
1766Here the comment part will be ignored. However, Vim will try to unmap
1767',ab ', which does not exist. Rewrite it as: >
1768
1769 :unmap ,ab| " comment
1770
1771
1772RESTORING THE VIEW
1773
Bram Moolenaar3a0d8092012-10-21 03:02:54 +02001774Sometimes you want to make a change and go back to where the cursor was.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001775Restoring the relative position would also be nice, so that the same line
1776appears at the top of the window.
1777 This example yanks the current line, puts it above the first line in the
1778file and then restores the view: >
1779
1780 map ,p ma"aYHmbgg"aP`bzt`a
1781
1782What this does: >
1783 ma"aYHmbgg"aP`bzt`a
1784< ma set mark a at cursor position
1785 "aY yank current line into register a
1786 Hmb go to top line in window and set mark b there
1787 gg go to first line in file
1788 "aP put the yanked line above it
1789 `b go back to top line in display
1790 zt position the text in the window as before
1791 `a go back to saved cursor position
1792
1793
1794PACKAGING
1795
1796To avoid your function names to interfere with functions that you get from
1797others, use this scheme:
1798- Prepend a unique string before each function name. I often use an
1799 abbreviation. For example, "OW_" is used for the option window functions.
1800- Put the definition of your functions together in a file. Set a global
1801 variable to indicate that the functions have been loaded. When sourcing the
1802 file again, first unload the functions.
1803Example: >
1804
1805 " This is the XXX package
1806
1807 if exists("XXX_loaded")
1808 delfun XXX_one
1809 delfun XXX_two
1810 endif
1811
1812 function XXX_one(a)
1813 ... body of function ...
1814 endfun
1815
1816 function XXX_two(b)
1817 ... body of function ...
1818 endfun
1819
1820 let XXX_loaded = 1
1821
1822==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00001823*41.11* Writing a plugin *write-plugin*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001824
1825You can write a Vim script in such a way that many people can use it. This is
1826called a plugin. Vim users can drop your script in their plugin directory and
1827use its features right away |add-plugin|.
1828
1829There are actually two types of plugins:
1830
1831 global plugins: For all types of files.
1832filetype plugins: Only for files of a specific type.
1833
1834In this section the first type is explained. Most items are also relevant for
1835writing filetype plugins. The specifics for filetype plugins are in the next
1836section |write-filetype-plugin|.
1837
1838
1839NAME
1840
1841First of all you must choose a name for your plugin. The features provided
1842by the plugin should be clear from its name. And it should be unlikely that
1843someone else writes a plugin with the same name but which does something
1844different. And please limit the name to 8 characters, to avoid problems on
1845old Windows systems.
1846
1847A script that corrects typing mistakes could be called "typecorr.vim". We
1848will use it here as an example.
1849
1850For the plugin to work for everybody, it should follow a few guidelines. This
1851will be explained step-by-step. The complete example plugin is at the end.
1852
1853
1854BODY
1855
1856Let's start with the body of the plugin, the lines that do the actual work: >
1857
1858 14 iabbrev teh the
1859 15 iabbrev otehr other
1860 16 iabbrev wnat want
1861 17 iabbrev synchronisation
1862 18 \ synchronization
1863 19 let s:count = 4
1864
1865The actual list should be much longer, of course.
1866
1867The line numbers have only been added to explain a few things, don't put them
1868in your plugin file!
1869
1870
1871HEADER
1872
1873You will probably add new corrections to the plugin and soon have several
Bram Moolenaard09acef2012-09-21 14:54:30 +02001874versions lying around. And when distributing this file, people will want to
Bram Moolenaar071d4272004-06-13 20:20:40 +00001875know who wrote this wonderful plugin and where they can send remarks.
1876Therefore, put a header at the top of your plugin: >
1877
1878 1 " Vim global plugin for correcting typing mistakes
1879 2 " Last Change: 2000 Oct 15
1880 3 " Maintainer: Bram Moolenaar <Bram@vim.org>
1881
1882About copyright and licensing: Since plugins are very useful and it's hardly
1883worth restricting their distribution, please consider making your plugin
1884either public domain or use the Vim |license|. A short note about this near
1885the top of the plugin should be sufficient. Example: >
1886
1887 4 " License: This file is placed in the public domain.
1888
1889
1890LINE CONTINUATION, AVOIDING SIDE EFFECTS *use-cpo-save*
1891
1892In line 18 above, the line-continuation mechanism is used |line-continuation|.
1893Users with 'compatible' set will run into trouble here, they will get an error
1894message. We can't just reset 'compatible', because that has a lot of side
1895effects. To avoid this, we will set the 'cpoptions' option to its Vim default
1896value and restore it later. That will allow the use of line-continuation and
1897make the script work for most people. It is done like this: >
1898
1899 11 let s:save_cpo = &cpo
1900 12 set cpo&vim
1901 ..
1902 42 let &cpo = s:save_cpo
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02001903 43 unlet s:save_cpo
Bram Moolenaar071d4272004-06-13 20:20:40 +00001904
1905We first store the old value of 'cpoptions' in the s:save_cpo variable. At
1906the end of the plugin this value is restored.
1907
1908Notice that a script-local variable is used |s:var|. A global variable could
1909already be in use for something else. Always use script-local variables for
1910things that are only used in the script.
1911
1912
1913NOT LOADING
1914
1915It's possible that a user doesn't always want to load this plugin. Or the
1916system administrator has dropped it in the system-wide plugin directory, but a
1917user has his own plugin he wants to use. Then the user must have a chance to
1918disable loading this specific plugin. This will make it possible: >
1919
Bram Moolenaarc5604bc2010-07-17 15:20:30 +02001920 6 if exists("g:loaded_typecorr")
Bram Moolenaar071d4272004-06-13 20:20:40 +00001921 7 finish
1922 8 endif
Bram Moolenaarc5604bc2010-07-17 15:20:30 +02001923 9 let g:loaded_typecorr = 1
Bram Moolenaar071d4272004-06-13 20:20:40 +00001924
1925This also avoids that when the script is loaded twice it would cause error
1926messages for redefining functions and cause trouble for autocommands that are
1927added twice.
1928
Bram Moolenaarc5604bc2010-07-17 15:20:30 +02001929The name is recommended to start with "loaded_" and then the file name of the
1930plugin, literally. The "g:" is prepended just to avoid mistakes when using
1931the variable in a function (without "g:" it would be a variable local to the
1932function).
1933
1934Using "finish" stops Vim from reading the rest of the file, it's much quicker
1935than using if-endif around the whole file.
1936
Bram Moolenaar071d4272004-06-13 20:20:40 +00001937
1938MAPPING
1939
1940Now let's make the plugin more interesting: We will add a mapping that adds a
1941correction for the word under the cursor. We could just pick a key sequence
1942for this mapping, but the user might already use it for something else. To
1943allow the user to define which keys a mapping in a plugin uses, the <Leader>
1944item can be used: >
1945
1946 22 map <unique> <Leader>a <Plug>TypecorrAdd
1947
1948The "<Plug>TypecorrAdd" thing will do the work, more about that further on.
1949
1950The user can set the "mapleader" variable to the key sequence that he wants
1951this mapping to start with. Thus if the user has done: >
1952
1953 let mapleader = "_"
1954
1955the mapping will define "_a". If the user didn't do this, the default value
1956will be used, which is a backslash. Then a map for "\a" will be defined.
1957
1958Note that <unique> is used, this will cause an error message if the mapping
1959already happened to exist. |:map-<unique>|
1960
1961But what if the user wants to define his own key sequence? We can allow that
1962with this mechanism: >
1963
1964 21 if !hasmapto('<Plug>TypecorrAdd')
1965 22 map <unique> <Leader>a <Plug>TypecorrAdd
1966 23 endif
1967
1968This checks if a mapping to "<Plug>TypecorrAdd" already exists, and only
1969defines the mapping from "<Leader>a" if it doesn't. The user then has a
1970chance of putting this in his vimrc file: >
1971
1972 map ,c <Plug>TypecorrAdd
1973
1974Then the mapped key sequence will be ",c" instead of "_a" or "\a".
1975
1976
1977PIECES
1978
1979If a script gets longer, you often want to break up the work in pieces. You
1980can use functions or mappings for this. But you don't want these functions
1981and mappings to interfere with the ones from other scripts. For example, you
1982could define a function Add(), but another script could try to define the same
1983function. To avoid this, we define the function local to the script by
1984prepending it with "s:".
1985
1986We will define a function that adds a new typing correction: >
1987
1988 30 function s:Add(from, correct)
1989 31 let to = input("type the correction for " . a:from . ": ")
1990 32 exe ":iabbrev " . a:from . " " . to
1991 ..
1992 36 endfunction
1993
1994Now we can call the function s:Add() from within this script. If another
1995script also defines s:Add(), it will be local to that script and can only
1996be called from the script it was defined in. There can also be a global Add()
1997function (without the "s:"), which is again another function.
1998
1999<SID> can be used with mappings. It generates a script ID, which identifies
2000the current script. In our typing correction plugin we use it like this: >
2001
2002 24 noremap <unique> <script> <Plug>TypecorrAdd <SID>Add
2003 ..
2004 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), 1)<CR>
2005
2006Thus when a user types "\a", this sequence is invoked: >
2007
2008 \a -> <Plug>TypecorrAdd -> <SID>Add -> :call <SID>Add()
2009
2010If another script would also map <SID>Add, it would get another script ID and
2011thus define another mapping.
2012
2013Note that instead of s:Add() we use <SID>Add() here. That is because the
2014mapping is typed by the user, thus outside of the script. The <SID> is
2015translated to the script ID, so that Vim knows in which script to look for
2016the Add() function.
2017
2018This is a bit complicated, but it's required for the plugin to work together
2019with other plugins. The basic rule is that you use <SID>Add() in mappings and
2020s:Add() in other places (the script itself, autocommands, user commands).
2021
2022We can also add a menu entry to do the same as the mapping: >
2023
2024 26 noremenu <script> Plugin.Add\ Correction <SID>Add
2025
2026The "Plugin" menu is recommended for adding menu items for plugins. In this
2027case only one item is used. When adding more items, creating a submenu is
2028recommended. For example, "Plugin.CVS" could be used for a plugin that offers
2029CVS operations "Plugin.CVS.checkin", "Plugin.CVS.checkout", etc.
2030
2031Note that in line 28 ":noremap" is used to avoid that any other mappings cause
2032trouble. Someone may have remapped ":call", for example. In line 24 we also
2033use ":noremap", but we do want "<SID>Add" to be remapped. This is why
2034"<script>" is used here. This only allows mappings which are local to the
2035script. |:map-<script>| The same is done in line 26 for ":noremenu".
2036|:menu-<script>|
2037
2038
2039<SID> AND <Plug> *using-<Plug>*
2040
2041Both <SID> and <Plug> are used to avoid that mappings of typed keys interfere
2042with mappings that are only to be used from other mappings. Note the
2043difference between using <SID> and <Plug>:
2044
2045<Plug> is visible outside of the script. It is used for mappings which the
2046 user might want to map a key sequence to. <Plug> is a special code
2047 that a typed key will never produce.
2048 To make it very unlikely that other plugins use the same sequence of
2049 characters, use this structure: <Plug> scriptname mapname
2050 In our example the scriptname is "Typecorr" and the mapname is "Add".
2051 This results in "<Plug>TypecorrAdd". Only the first character of
2052 scriptname and mapname is uppercase, so that we can see where mapname
2053 starts.
2054
2055<SID> is the script ID, a unique identifier for a script.
2056 Internally Vim translates <SID> to "<SNR>123_", where "123" can be any
2057 number. Thus a function "<SID>Add()" will have a name "<SNR>11_Add()"
2058 in one script, and "<SNR>22_Add()" in another. You can see this if
2059 you use the ":function" command to get a list of functions. The
2060 translation of <SID> in mappings is exactly the same, that's how you
2061 can call a script-local function from a mapping.
2062
2063
2064USER COMMAND
2065
2066Now let's add a user command to add a correction: >
2067
2068 38 if !exists(":Correct")
2069 39 command -nargs=1 Correct :call s:Add(<q-args>, 0)
2070 40 endif
2071
2072The user command is defined only if no command with the same name already
2073exists. Otherwise we would get an error here. Overriding the existing user
2074command with ":command!" is not a good idea, this would probably make the user
2075wonder why the command he defined himself doesn't work. |:command|
2076
2077
2078SCRIPT VARIABLES
2079
2080When a variable starts with "s:" it is a script variable. It can only be used
2081inside a script. Outside the script it's not visible. This avoids trouble
2082with using the same variable name in different scripts. The variables will be
2083kept as long as Vim is running. And the same variables are used when sourcing
2084the same script again. |s:var|
2085
2086The fun is that these variables can also be used in functions, autocommands
2087and user commands that are defined in the script. In our example we can add
2088a few lines to count the number of corrections: >
2089
2090 19 let s:count = 4
2091 ..
2092 30 function s:Add(from, correct)
2093 ..
2094 34 let s:count = s:count + 1
2095 35 echo s:count . " corrections now"
2096 36 endfunction
2097
2098First s:count is initialized to 4 in the script itself. When later the
2099s:Add() function is called, it increments s:count. It doesn't matter from
2100where the function was called, since it has been defined in the script, it
2101will use the local variables from this script.
2102
2103
2104THE RESULT
2105
2106Here is the resulting complete example: >
2107
2108 1 " Vim global plugin for correcting typing mistakes
2109 2 " Last Change: 2000 Oct 15
2110 3 " Maintainer: Bram Moolenaar <Bram@vim.org>
2111 4 " License: This file is placed in the public domain.
2112 5
Bram Moolenaarc5604bc2010-07-17 15:20:30 +02002113 6 if exists("g:loaded_typecorr")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002114 7 finish
2115 8 endif
Bram Moolenaarc5604bc2010-07-17 15:20:30 +02002116 9 let g:loaded_typecorr = 1
Bram Moolenaar071d4272004-06-13 20:20:40 +00002117 10
2118 11 let s:save_cpo = &cpo
2119 12 set cpo&vim
2120 13
2121 14 iabbrev teh the
2122 15 iabbrev otehr other
2123 16 iabbrev wnat want
2124 17 iabbrev synchronisation
2125 18 \ synchronization
2126 19 let s:count = 4
2127 20
2128 21 if !hasmapto('<Plug>TypecorrAdd')
2129 22 map <unique> <Leader>a <Plug>TypecorrAdd
2130 23 endif
2131 24 noremap <unique> <script> <Plug>TypecorrAdd <SID>Add
2132 25
2133 26 noremenu <script> Plugin.Add\ Correction <SID>Add
2134 27
2135 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), 1)<CR>
2136 29
2137 30 function s:Add(from, correct)
2138 31 let to = input("type the correction for " . a:from . ": ")
2139 32 exe ":iabbrev " . a:from . " " . to
2140 33 if a:correct | exe "normal viws\<C-R>\" \b\e" | endif
2141 34 let s:count = s:count + 1
2142 35 echo s:count . " corrections now"
2143 36 endfunction
2144 37
2145 38 if !exists(":Correct")
2146 39 command -nargs=1 Correct :call s:Add(<q-args>, 0)
2147 40 endif
2148 41
2149 42 let &cpo = s:save_cpo
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02002150 43 unlet s:save_cpo
Bram Moolenaar071d4272004-06-13 20:20:40 +00002151
2152Line 33 wasn't explained yet. It applies the new correction to the word under
2153the cursor. The |:normal| command is used to use the new abbreviation. Note
2154that mappings and abbreviations are expanded here, even though the function
2155was called from a mapping defined with ":noremap".
2156
2157Using "unix" for the 'fileformat' option is recommended. The Vim scripts will
2158then work everywhere. Scripts with 'fileformat' set to "dos" do not work on
2159Unix. Also see |:source_crnl|. To be sure it is set right, do this before
2160writing the file: >
2161
2162 :set fileformat=unix
2163
2164
2165DOCUMENTATION *write-local-help*
2166
2167It's a good idea to also write some documentation for your plugin. Especially
2168when its behavior can be changed by the user. See |add-local-help| for how
2169they are installed.
2170
2171Here is a simple example for a plugin help file, called "typecorr.txt": >
2172
2173 1 *typecorr.txt* Plugin for correcting typing mistakes
2174 2
2175 3 If you make typing mistakes, this plugin will have them corrected
2176 4 automatically.
2177 5
2178 6 There are currently only a few corrections. Add your own if you like.
2179 7
2180 8 Mappings:
2181 9 <Leader>a or <Plug>TypecorrAdd
2182 10 Add a correction for the word under the cursor.
2183 11
2184 12 Commands:
2185 13 :Correct {word}
2186 14 Add a correction for {word}.
2187 15
2188 16 *typecorr-settings*
2189 17 This plugin doesn't have any settings.
2190
2191The first line is actually the only one for which the format matters. It will
2192be extracted from the help file to be put in the "LOCAL ADDITIONS:" section of
2193help.txt |local-additions|. The first "*" must be in the first column of the
2194first line. After adding your help file do ":help" and check that the entries
2195line up nicely.
2196
2197You can add more tags inside ** in your help file. But be careful not to use
2198existing help tags. You would probably use the name of your plugin in most of
2199them, like "typecorr-settings" in the example.
2200
2201Using references to other parts of the help in || is recommended. This makes
2202it easy for the user to find associated help.
2203
2204
2205FILETYPE DETECTION *plugin-filetype*
2206
2207If your filetype is not already detected by Vim, you should create a filetype
2208detection snippet in a separate file. It is usually in the form of an
2209autocommand that sets the filetype when the file name matches a pattern.
2210Example: >
2211
2212 au BufNewFile,BufRead *.foo set filetype=foofoo
2213
2214Write this single-line file as "ftdetect/foofoo.vim" in the first directory
2215that appears in 'runtimepath'. For Unix that would be
2216"~/.vim/ftdetect/foofoo.vim". The convention is to use the name of the
2217filetype for the script name.
2218
2219You can make more complicated checks if you like, for example to inspect the
2220contents of the file to recognize the language. Also see |new-filetype|.
2221
2222
2223SUMMARY *plugin-special*
2224
2225Summary of special things to use in a plugin:
2226
2227s:name Variables local to the script.
2228
2229<SID> Script-ID, used for mappings and functions local to
2230 the script.
2231
2232hasmapto() Function to test if the user already defined a mapping
2233 for functionality the script offers.
2234
2235<Leader> Value of "mapleader", which the user defines as the
2236 keys that plugin mappings start with.
2237
2238:map <unique> Give a warning if a mapping already exists.
2239
2240:noremap <script> Use only mappings local to the script, not global
2241 mappings.
2242
2243exists(":Cmd") Check if a user command already exists.
2244
2245==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00002246*41.12* Writing a filetype plugin *write-filetype-plugin* *ftplugin*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002247
2248A filetype plugin is like a global plugin, except that it sets options and
2249defines mappings for the current buffer only. See |add-filetype-plugin| for
2250how this type of plugin is used.
2251
Bram Moolenaar7c626922005-02-07 22:01:03 +00002252First read the section on global plugins above |41.11|. All that is said there
Bram Moolenaar071d4272004-06-13 20:20:40 +00002253also applies to filetype plugins. There are a few extras, which are explained
2254here. The essential thing is that a filetype plugin should only have an
2255effect on the current buffer.
2256
2257
2258DISABLING
2259
2260If you are writing a filetype plugin to be used by many people, they need a
2261chance to disable loading it. Put this at the top of the plugin: >
2262
2263 " Only do this when not done yet for this buffer
2264 if exists("b:did_ftplugin")
2265 finish
2266 endif
2267 let b:did_ftplugin = 1
2268
2269This also needs to be used to avoid that the same plugin is executed twice for
2270the same buffer (happens when using an ":edit" command without arguments).
2271
2272Now users can disable loading the default plugin completely by making a
2273filetype plugin with only this line: >
2274
2275 let b:did_ftplugin = 1
2276
2277This does require that the filetype plugin directory comes before $VIMRUNTIME
2278in 'runtimepath'!
2279
2280If you do want to use the default plugin, but overrule one of the settings,
2281you can write the different setting in a script: >
2282
2283 setlocal textwidth=70
2284
2285Now write this in the "after" directory, so that it gets sourced after the
2286distributed "vim.vim" ftplugin |after-directory|. For Unix this would be
2287"~/.vim/after/ftplugin/vim.vim". Note that the default plugin will have set
2288"b:did_ftplugin", but it is ignored here.
2289
2290
2291OPTIONS
2292
2293To make sure the filetype plugin only affects the current buffer use the >
2294
2295 :setlocal
2296
2297command to set options. And only set options which are local to a buffer (see
2298the help for the option to check that). When using |:setlocal| for global
2299options or options local to a window, the value will change for many buffers,
2300and that is not what a filetype plugin should do.
2301
2302When an option has a value that is a list of flags or items, consider using
2303"+=" and "-=" to keep the existing value. Be aware that the user may have
2304changed an option value already. First resetting to the default value and
Bram Moolenaard58e9292011-02-09 17:07:58 +01002305then changing it is often a good idea. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002306
2307 :setlocal formatoptions& formatoptions+=ro
2308
2309
2310MAPPINGS
2311
2312To make sure mappings will only work in the current buffer use the >
2313
2314 :map <buffer>
2315
2316command. This needs to be combined with the two-step mapping explained above.
2317An example of how to define functionality in a filetype plugin: >
2318
2319 if !hasmapto('<Plug>JavaImport')
2320 map <buffer> <unique> <LocalLeader>i <Plug>JavaImport
2321 endif
2322 noremap <buffer> <unique> <Plug>JavaImport oimport ""<Left><Esc>
2323
2324|hasmapto()| is used to check if the user has already defined a map to
2325<Plug>JavaImport. If not, then the filetype plugin defines the default
2326mapping. This starts with |<LocalLeader>|, which allows the user to select
2327the key(s) he wants filetype plugin mappings to start with. The default is a
2328backslash.
2329"<unique>" is used to give an error message if the mapping already exists or
2330overlaps with an existing mapping.
2331|:noremap| is used to avoid that any other mappings that the user has defined
2332interferes. You might want to use ":noremap <script>" to allow remapping
2333mappings defined in this script that start with <SID>.
2334
2335The user must have a chance to disable the mappings in a filetype plugin,
2336without disabling everything. Here is an example of how this is done for a
2337plugin for the mail filetype: >
2338
2339 " Add mappings, unless the user didn't want this.
2340 if !exists("no_plugin_maps") && !exists("no_mail_maps")
2341 " Quote text by inserting "> "
2342 if !hasmapto('<Plug>MailQuote')
2343 vmap <buffer> <LocalLeader>q <Plug>MailQuote
2344 nmap <buffer> <LocalLeader>q <Plug>MailQuote
2345 endif
2346 vnoremap <buffer> <Plug>MailQuote :s/^/> /<CR>
2347 nnoremap <buffer> <Plug>MailQuote :.,$s/^/> /<CR>
2348 endif
2349
2350Two global variables are used:
Bram Moolenaare0720cb2017-03-29 13:48:40 +02002351|no_plugin_maps| disables mappings for all filetype plugins
2352|no_mail_maps| disables mappings for the "mail" filetype
Bram Moolenaar071d4272004-06-13 20:20:40 +00002353
2354
2355USER COMMANDS
2356
2357To add a user command for a specific file type, so that it can only be used in
2358one buffer, use the "-buffer" argument to |:command|. Example: >
2359
2360 :command -buffer Make make %:r.s
2361
2362
2363VARIABLES
2364
2365A filetype plugin will be sourced for each buffer of the type it's for. Local
2366script variables |s:var| will be shared between all invocations. Use local
2367buffer variables |b:var| if you want a variable specifically for one buffer.
2368
2369
2370FUNCTIONS
2371
2372When defining a function, this only needs to be done once. But the filetype
2373plugin will be sourced every time a file with this filetype will be opened.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02002374This construct makes sure the function is only defined once: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002375
2376 :if !exists("*s:Func")
2377 : function s:Func(arg)
2378 : ...
2379 : endfunction
2380 :endif
2381<
2382
Bram Moolenaar38a55632016-02-15 22:07:32 +01002383UNDO *undo_indent* *undo_ftplugin*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002384
2385When the user does ":setfiletype xyz" the effect of the previous filetype
2386should be undone. Set the b:undo_ftplugin variable to the commands that will
2387undo the settings in your filetype plugin. Example: >
2388
2389 let b:undo_ftplugin = "setlocal fo< com< tw< commentstring<"
2390 \ . "| unlet b:match_ignorecase b:match_words b:match_skip"
2391
2392Using ":setlocal" with "<" after the option name resets the option to its
2393global value. That is mostly the best way to reset the option value.
2394
2395This does require removing the "C" flag from 'cpoptions' to allow line
2396continuation, as mentioned above |use-cpo-save|.
2397
Bram Moolenaar38a55632016-02-15 22:07:32 +01002398For undoing the effect of an indent script, the b:undo_indent variable should
2399be set accordingly.
2400
Bram Moolenaar071d4272004-06-13 20:20:40 +00002401
2402FILE NAME
2403
2404The filetype must be included in the file name |ftplugin-name|. Use one of
2405these three forms:
2406
2407 .../ftplugin/stuff.vim
2408 .../ftplugin/stuff_foo.vim
2409 .../ftplugin/stuff/bar.vim
2410
2411"stuff" is the filetype, "foo" and "bar" are arbitrary names.
2412
2413
2414SUMMARY *ftplugin-special*
2415
2416Summary of special things to use in a filetype plugin:
2417
2418<LocalLeader> Value of "maplocalleader", which the user defines as
2419 the keys that filetype plugin mappings start with.
2420
2421:map <buffer> Define a mapping local to the buffer.
2422
2423:noremap <script> Only remap mappings defined in this script that start
2424 with <SID>.
2425
2426:setlocal Set an option for the current buffer only.
2427
2428:command -buffer Define a user command local to the buffer.
2429
2430exists("*s:Func") Check if a function was already defined.
2431
2432Also see |plugin-special|, the special things used for all plugins.
2433
2434==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00002435*41.13* Writing a compiler plugin *write-compiler-plugin*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002436
2437A compiler plugin sets options for use with a specific compiler. The user can
2438load it with the |:compiler| command. The main use is to set the
2439'errorformat' and 'makeprg' options.
2440
2441Easiest is to have a look at examples. This command will edit all the default
2442compiler plugins: >
2443
2444 :next $VIMRUNTIME/compiler/*.vim
2445
2446Use |:next| to go to the next plugin file.
2447
2448There are two special items about these files. First is a mechanism to allow
2449a user to overrule or add to the default file. The default files start with: >
2450
2451 :if exists("current_compiler")
2452 : finish
2453 :endif
2454 :let current_compiler = "mine"
2455
2456When you write a compiler file and put it in your personal runtime directory
2457(e.g., ~/.vim/compiler for Unix), you set the "current_compiler" variable to
2458make the default file skip the settings.
Bram Moolenaarc6039d82005-12-02 00:44:04 +00002459 *:CompilerSet*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002460The second mechanism is to use ":set" for ":compiler!" and ":setlocal" for
2461":compiler". Vim defines the ":CompilerSet" user command for this. However,
2462older Vim versions don't, thus your plugin should define it then. This is an
2463example: >
2464
2465 if exists(":CompilerSet") != 2
2466 command -nargs=* CompilerSet setlocal <args>
2467 endif
2468 CompilerSet errorformat& " use the default 'errorformat'
2469 CompilerSet makeprg=nmake
2470
2471When you write a compiler plugin for the Vim distribution or for a system-wide
2472runtime directory, use the mechanism mentioned above. When
2473"current_compiler" was already set by a user plugin nothing will be done.
2474
2475When you write a compiler plugin to overrule settings from a default plugin,
2476don't check "current_compiler". This plugin is supposed to be loaded
2477last, thus it should be in a directory at the end of 'runtimepath'. For Unix
2478that could be ~/.vim/after/compiler.
2479
2480==============================================================================
Bram Moolenaar05159a02005-02-26 23:04:13 +00002481*41.14* Writing a plugin that loads quickly *write-plugin-quickload*
2482
2483A plugin may grow and become quite long. The startup delay may become
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00002484noticeable, while you hardly ever use the plugin. Then it's time for a
Bram Moolenaar05159a02005-02-26 23:04:13 +00002485quickload plugin.
2486
2487The basic idea is that the plugin is loaded twice. The first time user
2488commands and mappings are defined that offer the functionality. The second
2489time the functions that implement the functionality are defined.
2490
2491It may sound surprising that quickload means loading a script twice. What we
2492mean is that it loads quickly the first time, postponing the bulk of the
2493script to the second time, which only happens when you actually use it. When
2494you always use the functionality it actually gets slower!
2495
Bram Moolenaar76916e62006-03-21 21:23:25 +00002496Note that since Vim 7 there is an alternative: use the |autoload|
2497functionality |41.15|.
2498
Bram Moolenaar05159a02005-02-26 23:04:13 +00002499The following example shows how it's done: >
2500
2501 " Vim global plugin for demonstrating quick loading
2502 " Last Change: 2005 Feb 25
2503 " Maintainer: Bram Moolenaar <Bram@vim.org>
2504 " License: This file is placed in the public domain.
2505
2506 if !exists("s:did_load")
2507 command -nargs=* BNRead call BufNetRead(<f-args>)
2508 map <F19> :call BufNetWrite('something')<CR>
2509
2510 let s:did_load = 1
2511 exe 'au FuncUndefined BufNet* source ' . expand('<sfile>')
2512 finish
2513 endif
2514
2515 function BufNetRead(...)
2516 echo 'BufNetRead(' . string(a:000) . ')'
2517 " read functionality here
2518 endfunction
2519
2520 function BufNetWrite(...)
2521 echo 'BufNetWrite(' . string(a:000) . ')'
2522 " write functionality here
2523 endfunction
2524
2525When the script is first loaded "s:did_load" is not set. The commands between
2526the "if" and "endif" will be executed. This ends in a |:finish| command, thus
2527the rest of the script is not executed.
2528
2529The second time the script is loaded "s:did_load" exists and the commands
2530after the "endif" are executed. This defines the (possible long)
2531BufNetRead() and BufNetWrite() functions.
2532
2533If you drop this script in your plugin directory Vim will execute it on
2534startup. This is the sequence of events that happens:
2535
25361. The "BNRead" command is defined and the <F19> key is mapped when the script
2537 is sourced at startup. A |FuncUndefined| autocommand is defined. The
2538 ":finish" command causes the script to terminate early.
2539
25402. The user types the BNRead command or presses the <F19> key. The
2541 BufNetRead() or BufNetWrite() function will be called.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00002542
Bram Moolenaar05159a02005-02-26 23:04:13 +000025433. Vim can't find the function and triggers the |FuncUndefined| autocommand
2544 event. Since the pattern "BufNet*" matches the invoked function, the
2545 command "source fname" will be executed. "fname" will be equal to the name
2546 of the script, no matter where it is located, because it comes from
2547 expanding "<sfile>" (see |expand()|).
2548
25494. The script is sourced again, the "s:did_load" variable exists and the
2550 functions are defined.
2551
2552Notice that the functions that are loaded afterwards match the pattern in the
2553|FuncUndefined| autocommand. You must make sure that no other plugin defines
2554functions that match this pattern.
2555
2556==============================================================================
2557*41.15* Writing library scripts *write-library-script*
2558
2559Some functionality will be required in several places. When this becomes more
2560than a few lines you will want to put it in one script and use it from many
2561scripts. We will call that one script a library script.
2562
2563Manually loading a library script is possible, so long as you avoid loading it
2564when it's already done. You can do this with the |exists()| function.
2565Example: >
2566
2567 if !exists('*MyLibFunction')
2568 runtime library/mylibscript.vim
2569 endif
2570 call MyLibFunction(arg)
2571
2572Here you need to know that MyLibFunction() is defined in a script
2573"library/mylibscript.vim" in one of the directories in 'runtimepath'.
2574
2575To make this a bit simpler Vim offers the autoload mechanism. Then the
2576example looks like this: >
2577
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002578 call mylib#myfunction(arg)
Bram Moolenaar05159a02005-02-26 23:04:13 +00002579
2580That's a lot simpler, isn't it? Vim will recognize the function name and when
2581it's not defined search for the script "autoload/mylib.vim" in 'runtimepath'.
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002582That script must define the "mylib#myfunction()" function.
Bram Moolenaar05159a02005-02-26 23:04:13 +00002583
2584You can put many other functions in the mylib.vim script, you are free to
2585organize your functions in library scripts. But you must use function names
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00002586where the part before the '#' matches the script name. Otherwise Vim would
2587not know what script to load.
Bram Moolenaar05159a02005-02-26 23:04:13 +00002588
Bram Moolenaard1f56e62006-02-22 21:25:37 +00002589If you get really enthusiastic and write lots of library scripts, you may
Bram Moolenaar05159a02005-02-26 23:04:13 +00002590want to use subdirectories. Example: >
2591
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002592 call netlib#ftp#read('somefile')
Bram Moolenaar05159a02005-02-26 23:04:13 +00002593
2594For Unix the library script used for this could be:
2595
2596 ~/.vim/autoload/netlib/ftp.vim
2597
2598Where the function is defined like this: >
2599
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002600 function netlib#ftp#read(fname)
Bram Moolenaar05159a02005-02-26 23:04:13 +00002601 " Read the file fname through ftp
2602 endfunction
2603
2604Notice that the name the function is defined with is exactly the same as the
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00002605name used for calling the function. And the part before the last '#'
Bram Moolenaar05159a02005-02-26 23:04:13 +00002606exactly matches the subdirectory and script name.
2607
2608You can use the same mechanism for variables: >
2609
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002610 let weekdays = dutch#weekdays
Bram Moolenaar05159a02005-02-26 23:04:13 +00002611
2612This will load the script "autoload/dutch.vim", which should contain something
2613like: >
2614
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002615 let dutch#weekdays = ['zondag', 'maandag', 'dinsdag', 'woensdag',
Bram Moolenaar05159a02005-02-26 23:04:13 +00002616 \ 'donderdag', 'vrijdag', 'zaterdag']
2617
2618Further reading: |autoload|.
2619
2620==============================================================================
Bram Moolenaar76916e62006-03-21 21:23:25 +00002621*41.16* Distributing Vim scripts *distribute-script*
2622
2623Vim users will look for scripts on the Vim website: http://www.vim.org.
2624If you made something that is useful for others, share it!
2625
2626Vim scripts can be used on any system. There might not be a tar or gzip
2627command. If you want to pack files together and/or compress them the "zip"
2628utility is recommended.
2629
2630For utmost portability use Vim itself to pack scripts together. This can be
2631done with the Vimball utility. See |vimball|.
2632
Bram Moolenaarc01140a2006-03-24 22:21:52 +00002633It's good if you add a line to allow automatic updating. See |glvs-plugins|.
2634
Bram Moolenaar76916e62006-03-21 21:23:25 +00002635==============================================================================
Bram Moolenaar071d4272004-06-13 20:20:40 +00002636
2637Next chapter: |usr_42.txt| Add new menus
2638
Bram Moolenaard473c8c2018-08-11 18:00:22 +02002639Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: