blob: 98e9a10a61e7a1c5f5dc153b917b39dfafd34bbb [file] [log] [blame]
Bram Moolenaar98a29d02021-01-18 19:55:44 +01001*usr_41.txt* For Vim version 8.2. Last change: 2021 Jan 13
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
Bram Moolenaar65e0d772020-06-14 17:29:55 +020044 If you are familiar with Python, you can find a comparison between
45 Python and Vim script here, with pointers to other documents:
46 https://gist.github.com/yegappan/16d964a37ead0979b05e655aa036cad0
Bram Moolenaare7b1ea02020-08-07 19:54:59 +020047 And if you are familiar with JavaScript:
Bram Moolenaar65e0d772020-06-14 17:29:55 +020048 https://w0rp.com/blog/post/vim-script-for-the-javascripter/
Bram Moolenaarebacddb2020-06-04 15:22:21 +020049
Bram Moolenaar071d4272004-06-13 20:20:40 +000050Let's start with a simple example: >
51
52 :let i = 1
53 :while i < 5
54 : echo "count is" i
Bram Moolenaar7c626922005-02-07 22:01:03 +000055 : let i += 1
Bram Moolenaar071d4272004-06-13 20:20:40 +000056 :endwhile
57<
58 Note:
59 The ":" characters are not really needed here. You only need to use
60 them when you type a command. In a Vim script file they can be left
61 out. We will use them here anyway to make clear these are colon
62 commands and make them stand out from Normal mode commands.
Bram Moolenaar7c626922005-02-07 22:01:03 +000063 Note:
64 You can try out the examples by yanking the lines from the text here
65 and executing them with :@"
Bram Moolenaar071d4272004-06-13 20:20:40 +000066
Bram Moolenaar7c626922005-02-07 22:01:03 +000067The output of the example code is:
68
69 count is 1 ~
70 count is 2 ~
71 count is 3 ~
72 count is 4 ~
73
74In the first line the ":let" command assigns a value to a variable. The
75generic form is: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000076
77 :let {variable} = {expression}
78
79In this case the variable name is "i" and the expression is a simple value,
80the number one.
81 The ":while" command starts a loop. The generic form is: >
82
83 :while {condition}
84 : {statements}
85 :endwhile
86
87The statements until the matching ":endwhile" are executed for as long as the
88condition is true. The condition used here is the expression "i < 5". This
89is true when the variable i is smaller than five.
Bram Moolenaar071d4272004-06-13 20:20:40 +000090 Note:
91 If you happen to write a while loop that keeps on running, you can
92 interrupt it by pressing CTRL-C (CTRL-Break on MS-Windows).
93
Bram Moolenaar7c626922005-02-07 22:01:03 +000094The ":echo" command prints its arguments. In this case the string "count is"
95and the value of the variable i. Since i is one, this will print:
96
97 count is 1 ~
98
99Then there is the ":let i += 1" command. This does the same thing as
100":let i = i + 1". This adds one to the variable i and assigns the new value
101to the same variable.
Bram Moolenaar65e0d772020-06-14 17:29:55 +0200102Note: this is how it works in legacy Vim script, which is what we discuss in
103this file. In Vim9 script it's a bit different, see |usr_46.txt|.
Bram Moolenaar7c626922005-02-07 22:01:03 +0000104
105The example was given to explain the commands, but would you really want to
Bram Moolenaar214641f2017-03-05 17:04:09 +0100106make such a loop, it can be written much more compact: >
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000107
108 :for i in range(1, 4)
109 : echo "count is" i
110 :endfor
111
Bram Moolenaar7c626922005-02-07 22:01:03 +0000112We won't explain how |:for| and |range()| work until later. Follow the links
113if you are impatient.
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000114
Bram Moolenaar071d4272004-06-13 20:20:40 +0000115
Bram Moolenaar7dd64a32019-05-31 21:41:05 +0200116FOUR KINDS OF NUMBERS
Bram Moolenaar071d4272004-06-13 20:20:40 +0000117
Bram Moolenaar7dd64a32019-05-31 21:41:05 +0200118Numbers can be decimal, hexadecimal, octal or binary. A hexadecimal number
119starts with "0x" or "0X". For example "0x1f" is decimal 31. An octal number
120starts with a zero. "017" is decimal 15. A binary number starts with "0b" or
121"0B". For example "0b101" is decimal 5. Careful: don't put a zero before a
122decimal number, it will be interpreted as an octal number!
Bram Moolenaar071d4272004-06-13 20:20:40 +0000123 The ":echo" command always prints decimal numbers. Example: >
124
Bram Moolenaar82be4842021-01-11 19:40:15 +0100125 :echo 0x7f 0o36
Bram Moolenaar071d4272004-06-13 20:20:40 +0000126< 127 30 ~
127
Bram Moolenaar7dd64a32019-05-31 21:41:05 +0200128A number is made negative with a minus sign. This also works for hexadecimal,
129octal and binary numbers. A minus sign is also used for subtraction. Compare
130this with the previous example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000131
Bram Moolenaar82be4842021-01-11 19:40:15 +0100132 :echo 0x7f -0o36
Bram Moolenaar071d4272004-06-13 20:20:40 +0000133< 97 ~
134
135White space in an expression is ignored. However, it's recommended to use it
136for separating items, to make the expression easier to read. For example, to
Bram Moolenaar7c626922005-02-07 22:01:03 +0000137avoid the confusion with a negative number above, put a space between the
138minus sign and the following number: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000139
Bram Moolenaar82be4842021-01-11 19:40:15 +0100140 :echo 0x7f - 0o36
Bram Moolenaar071d4272004-06-13 20:20:40 +0000141
142==============================================================================
143*41.2* Variables
144
145A variable name consists of ASCII letters, digits and the underscore. It
146cannot start with a digit. Valid variable names are:
147
148 counter
149 _aap3
150 very_long_variable_name_with_underscores
151 FuncLength
152 LENGTH
153
154Invalid names are "foo+bar" and "6var".
155 These variables are global. To see a list of currently defined variables
156use this command: >
157
158 :let
159
160You can use global variables everywhere. This also means that when the
161variable "count" is used in one script file, it might also be used in another
162file. This leads to confusion at least, and real problems at worst. To avoid
163this, you can use a variable local to a script file by prepending "s:". For
164example, one script contains this code: >
165
166 :let s:count = 1
167 :while s:count < 5
168 : source other.vim
Bram Moolenaar7c626922005-02-07 22:01:03 +0000169 : let s:count += 1
Bram Moolenaar071d4272004-06-13 20:20:40 +0000170 :endwhile
171
172Since "s:count" is local to this script, you can be sure that sourcing the
173"other.vim" script will not change this variable. If "other.vim" also uses an
174"s:count" variable, it will be a different copy, local to that script. More
175about script-local variables here: |script-variable|.
176
177There are more kinds of variables, see |internal-variables|. The most often
178used ones are:
179
180 b:name variable local to a buffer
181 w:name variable local to a window
182 g:name global variable (also in a function)
183 v:name variable predefined by Vim
184
185
186DELETING VARIABLES
187
188Variables take up memory and show up in the output of the ":let" command. To
189delete a variable use the ":unlet" command. Example: >
190
191 :unlet s:count
192
193This deletes the script-local variable "s:count" to free up the memory it
194uses. If you are not sure if the variable exists, and don't want an error
195message when it doesn't, append !: >
196
197 :unlet! s:count
198
199When a script finishes, the local variables used there will not be
200automatically freed. The next time the script executes, it can still use the
201old value. Example: >
202
203 :if !exists("s:call_count")
204 : let s:call_count = 0
205 :endif
206 :let s:call_count = s:call_count + 1
207 :echo "called" s:call_count "times"
208
209The "exists()" function checks if a variable has already been defined. Its
210argument is the name of the variable you want to check. Not the variable
211itself! If you would do this: >
212
213 :if !exists(s:call_count)
214
215Then the value of s:call_count will be used as the name of the variable that
216exists() checks. That's not what you want.
217 The exclamation mark ! negates a value. When the value was true, it
218becomes false. When it was false, it becomes true. You can read it as "not".
219Thus "if !exists()" can be read as "if not exists()".
Bram Moolenaar7c626922005-02-07 22:01:03 +0000220 What Vim calls true is anything that is not zero. Zero is false.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000221 Note:
Bram Moolenaar7c626922005-02-07 22:01:03 +0000222 Vim automatically converts a string to a number when it is looking for
223 a number. When using a string that doesn't start with a digit the
224 resulting number is zero. Thus look out for this: >
225 :if "true"
226< The "true" will be interpreted as a zero, thus as false!
Bram Moolenaar071d4272004-06-13 20:20:40 +0000227
228
229STRING VARIABLES AND CONSTANTS
230
231So far only numbers were used for the variable value. Strings can be used as
Bram Moolenaar7c626922005-02-07 22:01:03 +0000232well. Numbers and strings are the basic types of variables that Vim supports.
233The type is dynamic, it is set each time when assigning a value to the
234variable with ":let". More about types in |41.8|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000235 To assign a string value to a variable, you need to use a string constant.
236There are two types of these. First the string in double quotes: >
237
238 :let name = "peter"
239 :echo name
240< peter ~
241
242If you want to include a double quote inside the string, put a backslash in
243front of it: >
244
245 :let name = "\"peter\""
246 :echo name
247< "peter" ~
248
249To avoid the need for a backslash, you can use a string in single quotes: >
250
251 :let name = '"peter"'
252 :echo name
253< "peter" ~
254
Bram Moolenaar7c626922005-02-07 22:01:03 +0000255Inside a single-quote string all the characters are as they are. Only the
256single quote itself is special: you need to use two to get one. A backslash
257is taken literally, thus you can't use it to change the meaning of the
Bram Moolenaar071d4272004-06-13 20:20:40 +0000258character after it.
259 In double-quote strings it is possible to use special characters. Here are
260a few useful ones:
261
262 \t <Tab>
263 \n <NL>, line break
264 \r <CR>, <Enter>
265 \e <Esc>
266 \b <BS>, backspace
267 \" "
268 \\ \, backslash
269 \<Esc> <Esc>
270 \<C-W> CTRL-W
271
272The last two are just examples. The "\<name>" form can be used to include
273the special key "name".
274 See |expr-quote| for the full list of special items in a string.
275
276==============================================================================
277*41.3* Expressions
278
279Vim has a rich, yet simple way to handle expressions. You can read the
280definition here: |expression-syntax|. Here we will show the most common
281items.
282 The numbers, strings and variables mentioned above are expressions by
283themselves. Thus everywhere an expression is expected, you can use a number,
284string or variable. Other basic items in an expression are:
285
286 $NAME environment variable
287 &name option
288 @r register
289
290Examples: >
291
292 :echo "The value of 'tabstop' is" &ts
293 :echo "Your home directory is" $HOME
294 :if @a > 5
295
296The &name form can be used to save an option value, set it to a new value,
297do something and restore the old value. Example: >
298
299 :let save_ic = &ic
300 :set noic
301 :/The Start/,$delete
302 :let &ic = save_ic
303
304This makes sure the "The Start" pattern is used with the 'ignorecase' option
Bram Moolenaar7c626922005-02-07 22:01:03 +0000305off. Still, it keeps the value that the user had set. (Another way to do
306this would be to add "\C" to the pattern, see |/\C|.)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000307
308
309MATHEMATICS
310
311It becomes more interesting if we combine these basic items. Let's start with
312mathematics on numbers:
313
314 a + b add
315 a - b subtract
316 a * b multiply
317 a / b divide
318 a % b modulo
319
320The usual precedence is used. Example: >
321
322 :echo 10 + 5 * 2
323< 20 ~
324
Bram Moolenaar00654022011-02-25 14:42:19 +0100325Grouping is done with parentheses. No surprises here. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000326
327 :echo (10 + 5) * 2
328< 30 ~
329
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200330Strings can be concatenated with ".." (see |expr6|). Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000331
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200332 :echo "foo" .. "bar"
Bram Moolenaar071d4272004-06-13 20:20:40 +0000333< foobar ~
334
335When the ":echo" command gets multiple arguments, it separates them with a
336space. In the example the argument is a single expression, thus no space is
337inserted.
338
339Borrowed from the C language is the conditional expression:
340
341 a ? b : c
342
343If "a" evaluates to true "b" is used, otherwise "c" is used. Example: >
344
345 :let i = 4
346 :echo i > 5 ? "i is big" : "i is small"
347< i is small ~
348
349The three parts of the constructs are always evaluated first, thus you could
350see it work as:
351
352 (a) ? (b) : (c)
353
354==============================================================================
355*41.4* Conditionals
356
357The ":if" commands executes the following statements, until the matching
358":endif", only when a condition is met. The generic form is:
359
360 :if {condition}
361 {statements}
362 :endif
363
364Only when the expression {condition} evaluates to true (non-zero) will the
365{statements} be executed. These must still be valid commands. If they
366contain garbage, Vim won't be able to find the ":endif".
367 You can also use ":else". The generic form for this is:
368
369 :if {condition}
370 {statements}
371 :else
372 {statements}
373 :endif
374
375The second {statements} is only executed if the first one isn't.
376 Finally, there is ":elseif":
377
378 :if {condition}
379 {statements}
380 :elseif {condition}
381 {statements}
382 :endif
383
384This works just like using ":else" and then "if", but without the need for an
385extra ":endif".
386 A useful example for your vimrc file is checking the 'term' option and
387doing something depending upon its value: >
388
389 :if &term == "xterm"
390 : " Do stuff for xterm
391 :elseif &term == "vt100"
392 : " Do stuff for a vt100 terminal
393 :else
394 : " Do something for other terminals
395 :endif
396
397
398LOGIC OPERATIONS
399
400We already used some of them in the examples. These are the most often used
401ones:
402
403 a == b equal to
404 a != b not equal to
405 a > b greater than
406 a >= b greater than or equal to
407 a < b less than
408 a <= b less than or equal to
409
410The result is one if the condition is met and zero otherwise. An example: >
411
Bram Moolenaar7c626922005-02-07 22:01:03 +0000412 :if v:version >= 700
Bram Moolenaar071d4272004-06-13 20:20:40 +0000413 : echo "congratulations"
414 :else
415 : echo "you are using an old version, upgrade!"
416 :endif
417
418Here "v:version" is a variable defined by Vim, which has the value of the Vim
419version. 600 is for version 6.0. Version 6.1 has the value 601. This is
420very useful to write a script that works with multiple versions of Vim.
421|v:version|
422
423The logic operators work both for numbers and strings. When comparing two
424strings, the mathematical difference is used. This compares byte values,
425which may not be right for some languages.
426 When comparing a string with a number, the string is first converted to a
427number. This is a bit tricky, because when a string doesn't look like a
428number, the number zero is used. Example: >
429
430 :if 0 == "one"
431 : echo "yes"
432 :endif
433
434This will echo "yes", because "one" doesn't look like a number, thus it is
435converted to the number zero.
436
437For strings there are two more items:
438
439 a =~ b matches with
440 a !~ b does not match with
441
442The left item "a" is used as a string. The right item "b" is used as a
443pattern, like what's used for searching. Example: >
444
445 :if str =~ " "
446 : echo "str contains a space"
447 :endif
448 :if str !~ '\.$'
449 : echo "str does not end in a full stop"
450 :endif
451
452Notice the use of a single-quote string for the pattern. This is useful,
Bram Moolenaar7c626922005-02-07 22:01:03 +0000453because backslashes would need to be doubled in a double-quote string and
454patterns tend to contain many backslashes.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000455
456The 'ignorecase' option is used when comparing strings. When you don't want
457that, append "#" to match case and "?" to ignore case. Thus "==?" compares
458two strings to be equal while ignoring case. And "!~#" checks if a pattern
459doesn't match, also checking the case of letters. For the full table see
460|expr-==|.
461
462
463MORE LOOPING
464
465The ":while" command was already mentioned. Two more statements can be used
466in between the ":while" and the ":endwhile":
467
468 :continue Jump back to the start of the while loop; the
469 loop continues.
470 :break Jump forward to the ":endwhile"; the loop is
471 discontinued.
472
473Example: >
474
475 :while counter < 40
476 : call do_something()
477 : if skip_flag
478 : continue
479 : endif
480 : if finished_flag
481 : break
482 : endif
483 : sleep 50m
484 :endwhile
485
486The ":sleep" command makes Vim take a nap. The "50m" specifies fifty
487milliseconds. Another example is ":sleep 4", which sleeps for four seconds.
488
Bram Moolenaar7c626922005-02-07 22:01:03 +0000489Even more looping can be done with the ":for" command, see below in |41.8|.
490
Bram Moolenaar071d4272004-06-13 20:20:40 +0000491==============================================================================
492*41.5* Executing an expression
493
494So far the commands in the script were executed by Vim directly. The
495":execute" command allows executing the result of an expression. This is a
496very powerful way to build commands and execute them.
497 An example is to jump to a tag, which is contained in a variable: >
498
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200499 :execute "tag " .. tag_name
Bram Moolenaar071d4272004-06-13 20:20:40 +0000500
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200501The ".." is used to concatenate the string "tag " with the value of variable
Bram Moolenaar071d4272004-06-13 20:20:40 +0000502"tag_name". Suppose "tag_name" has the value "get_cmd", then the command that
503will be executed is: >
504
505 :tag get_cmd
506
507The ":execute" command can only execute colon commands. The ":normal" command
508executes Normal mode commands. However, its argument is not an expression but
509the literal command characters. Example: >
510
511 :normal gg=G
512
513This jumps to the first line and formats all lines with the "=" operator.
514 To make ":normal" work with an expression, combine ":execute" with it.
515Example: >
516
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200517 :execute "normal " .. normal_commands
Bram Moolenaar071d4272004-06-13 20:20:40 +0000518
519The variable "normal_commands" must contain the Normal mode commands.
520 Make sure that the argument for ":normal" is a complete command. Otherwise
521Vim will run into the end of the argument and abort the command. For example,
522if you start Insert mode, you must leave Insert mode as well. This works: >
523
524 :execute "normal Inew text \<Esc>"
525
526This inserts "new text " in the current line. Notice the use of the special
527key "\<Esc>". This avoids having to enter a real <Esc> character in your
528script.
529
Bram Moolenaar7c626922005-02-07 22:01:03 +0000530If you don't want to execute a string but evaluate it to get its expression
531value, you can use the eval() function: >
532
533 :let optname = "path"
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200534 :let optval = eval('&' .. optname)
Bram Moolenaar7c626922005-02-07 22:01:03 +0000535
536A "&" character is prepended to "path", thus the argument to eval() is
537"&path". The result will then be the value of the 'path' option.
538 The same thing can be done with: >
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200539 :exe 'let optval = &' .. optname
Bram Moolenaar7c626922005-02-07 22:01:03 +0000540
Bram Moolenaar071d4272004-06-13 20:20:40 +0000541==============================================================================
542*41.6* Using functions
543
544Vim defines many functions and provides a large amount of functionality that
545way. A few examples will be given in this section. You can find the whole
546list here: |functions|.
547
548A function is called with the ":call" command. The parameters are passed in
Bram Moolenaar00654022011-02-25 14:42:19 +0100549between parentheses separated by commas. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000550
551 :call search("Date: ", "W")
552
553This calls the search() function, with arguments "Date: " and "W". The
554search() function uses its first argument as a search pattern and the second
555one as flags. The "W" flag means the search doesn't wrap around the end of
556the file.
557
558A function can be called in an expression. Example: >
559
560 :let line = getline(".")
561 :let repl = substitute(line, '\a', "*", "g")
562 :call setline(".", repl)
563
Bram Moolenaar7c626922005-02-07 22:01:03 +0000564The getline() function obtains a line from the current buffer. Its argument
565is a specification of the line number. In this case "." is used, which means
566the line where the cursor is.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000567 The substitute() function does something similar to the ":substitute"
568command. The first argument is the string on which to perform the
569substitution. The second argument is the pattern, the third the replacement
570string. Finally, the last arguments are the flags.
571 The setline() function sets the line, specified by the first argument, to a
572new string, the second argument. In this example the line under the cursor is
573replaced with the result of the substitute(). Thus the effect of the three
574statements is equal to: >
575
576 :substitute/\a/*/g
577
578Using the functions becomes more interesting when you do more work before and
579after the substitute() call.
580
581
582FUNCTIONS *function-list*
583
584There are many functions. We will mention them here, grouped by what they are
585used for. You can find an alphabetical list here: |functions|. Use CTRL-] on
586the function name to jump to detailed help on it.
587
Bram Moolenaara3f41662010-07-11 19:01:06 +0200588String manipulation: *string-functions*
Bram Moolenaar9d401282019-04-06 13:18:12 +0200589 nr2char() get a character by its number value
590 list2str() get a character string from a list of numbers
591 char2nr() get number value of a character
592 str2list() get list of numbers from a string
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000593 str2nr() convert a string to a Number
594 str2float() convert a string to a Float
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000595 printf() format a string according to % items
Bram Moolenaar071d4272004-06-13 20:20:40 +0000596 escape() escape characters in a string with a '\'
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000597 shellescape() escape a string for use with a shell command
598 fnameescape() escape a file name for use with a Vim command
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000599 tr() translate characters from one set to another
Bram Moolenaar071d4272004-06-13 20:20:40 +0000600 strtrans() translate a string to make it printable
601 tolower() turn a string to lowercase
602 toupper() turn a string to uppercase
Bram Moolenaar4e4473c2020-08-28 22:24:57 +0200603 charclass() class of a character
Bram Moolenaar071d4272004-06-13 20:20:40 +0000604 match() position where a pattern matches in a string
605 matchend() position where a pattern match ends in a string
Bram Moolenaar635414d2020-09-11 22:25:15 +0200606 matchfuzzy() fuzzy matches a string in a list of strings
Bram Moolenaar4f73b8e2020-09-22 20:33:50 +0200607 matchfuzzypos() fuzzy matches a string in a list of strings
Bram Moolenaar071d4272004-06-13 20:20:40 +0000608 matchstr() match of a pattern in a string
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +0200609 matchstrpos() match and positions of a pattern in a string
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000610 matchlist() like matchstr() and also return submatches
Bram Moolenaar071d4272004-06-13 20:20:40 +0000611 stridx() first index of a short string in a long string
612 strridx() last index of a short string in a long string
Bram Moolenaar8d043172014-01-23 14:24:41 +0100613 strlen() length of a string in bytes
614 strchars() length of a string in characters
615 strwidth() size of string when displayed
616 strdisplaywidth() size of string when displayed, deals with tabs
Bram Moolenaar08aac3c2020-08-28 21:04:24 +0200617 setcellwidths() set character cell width overrides
Bram Moolenaar071d4272004-06-13 20:20:40 +0000618 substitute() substitute a pattern match with a string
Bram Moolenaar251e1912011-06-19 05:09:16 +0200619 submatch() get a specific match in ":s" and substitute()
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200620 strpart() get part of a string using byte index
621 strcharpart() get part of a string using char index
Bram Moolenaar6601b622021-01-13 21:47:15 +0100622 slice() take a slice of a string, using char index in
623 Vim9 script
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200624 strgetchar() get character from a string using char index
Bram Moolenaar071d4272004-06-13 20:20:40 +0000625 expand() expand special keywords
Bram Moolenaar80dad482019-06-09 17:22:31 +0200626 expandcmd() expand a command like done for `:edit`
Bram Moolenaar071d4272004-06-13 20:20:40 +0000627 iconv() convert text from one encoding to another
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000628 byteidx() byte index of a character in a string
Bram Moolenaar8d043172014-01-23 14:24:41 +0100629 byteidxcomp() like byteidx() but count composing characters
Bram Moolenaar17793ef2020-12-28 12:56:58 +0100630 charidx() character index of a byte in a string
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000631 repeat() repeat a string multiple times
632 eval() evaluate a string expression
Bram Moolenaar063b9d12016-07-09 20:21:48 +0200633 execute() execute an Ex command and get the output
Bram Moolenaar7dd64a32019-05-31 21:41:05 +0200634 win_execute() like execute() but in a specified window
Bram Moolenaarb730f0c2018-11-25 03:56:26 +0100635 trim() trim characters from a string
Bram Moolenaar0b39c3f2020-08-30 15:52:10 +0200636 gettext() lookup message translation
Bram Moolenaar071d4272004-06-13 20:20:40 +0000637
Bram Moolenaara3f41662010-07-11 19:01:06 +0200638List manipulation: *list-functions*
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000639 get() get an item without error for wrong index
640 len() number of items in a List
641 empty() check if List is empty
642 insert() insert an item somewhere in a List
643 add() append an item to a List
644 extend() append a List to a List
Bram Moolenaarb0e6b512021-01-12 20:23:40 +0100645 extendnew() make a new List and append items
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000646 remove() remove one or more items from a List
647 copy() make a shallow copy of a List
648 deepcopy() make a full copy of a List
649 filter() remove selected items from a List
650 map() change each List item
Bram Moolenaarea696852020-11-09 18:31:39 +0100651 mapnew() make a new List with changed items
Bram Moolenaarebacddb2020-06-04 15:22:21 +0200652 reduce() reduce a List to a value
Bram Moolenaar6601b622021-01-13 21:47:15 +0100653 slice() take a slice of a List
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000654 sort() sort a List
655 reverse() reverse the order of a List
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +0100656 uniq() remove copies of repeated adjacent items
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000657 split() split a String into a List
658 join() join List items into a String
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000659 range() return a List with a sequence of numbers
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000660 string() String representation of a List
661 call() call a function with List as arguments
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000662 index() index of a value in a List
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000663 max() maximum value in a List
664 min() minimum value in a List
665 count() count number of times a value appears in a List
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000666 repeat() repeat a List multiple times
Bram Moolenaar077a1e62020-06-08 20:50:43 +0200667 flatten() flatten a List
Bram Moolenaar3b690062021-02-01 20:14:51 +0100668 flattennew() flatten a copy of a List
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000669
Bram Moolenaara3f41662010-07-11 19:01:06 +0200670Dictionary manipulation: *dict-functions*
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000671 get() get an entry without an error for a wrong key
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000672 len() number of entries in a Dictionary
673 has_key() check whether a key appears in a Dictionary
674 empty() check if Dictionary is empty
675 remove() remove an entry from a Dictionary
676 extend() add entries from one Dictionary to another
Bram Moolenaarb0e6b512021-01-12 20:23:40 +0100677 extendnew() make a new Dictionary and append items
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000678 filter() remove selected entries from a Dictionary
679 map() change each Dictionary entry
Bram Moolenaarea696852020-11-09 18:31:39 +0100680 mapnew() make a new Dictionary with changed items
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000681 keys() get List of Dictionary keys
682 values() get List of Dictionary values
683 items() get List of Dictionary key-value pairs
684 copy() make a shallow copy of a Dictionary
685 deepcopy() make a full copy of a Dictionary
686 string() String representation of a Dictionary
687 max() maximum value in a Dictionary
688 min() minimum value in a Dictionary
689 count() count number of times a value appears
690
Bram Moolenaara3f41662010-07-11 19:01:06 +0200691Floating point computation: *float-functions*
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000692 float2nr() convert Float to Number
693 abs() absolute value (also works for Number)
694 round() round off
695 ceil() round up
696 floor() round down
697 trunc() remove value after decimal point
Bram Moolenaar8d043172014-01-23 14:24:41 +0100698 fmod() remainder of division
699 exp() exponential
700 log() natural logarithm (logarithm to base e)
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000701 log10() logarithm to base 10
702 pow() value of x to the exponent y
703 sqrt() square root
704 sin() sine
705 cos() cosine
Bram Moolenaar662db672011-03-22 14:05:35 +0100706 tan() tangent
707 asin() arc sine
708 acos() arc cosine
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000709 atan() arc tangent
Bram Moolenaar662db672011-03-22 14:05:35 +0100710 atan2() arc tangent
711 sinh() hyperbolic sine
712 cosh() hyperbolic cosine
713 tanh() hyperbolic tangent
Bram Moolenaarebacddb2020-06-04 15:22:21 +0200714 isinf() check for infinity
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200715 isnan() check for not a number
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000716
Bram Moolenaarb6b046b2011-12-30 13:11:27 +0100717Other computation: *bitwise-function*
718 and() bitwise AND
719 invert() bitwise invert
720 or() bitwise OR
721 xor() bitwise XOR
Bram Moolenaar8d043172014-01-23 14:24:41 +0100722 sha256() SHA-256 hash
Bram Moolenaarebacddb2020-06-04 15:22:21 +0200723 rand() get a pseudo-random number
724 srand() initialize seed used by rand()
Bram Moolenaarb6b046b2011-12-30 13:11:27 +0100725
Bram Moolenaara3f41662010-07-11 19:01:06 +0200726Variables: *var-functions*
Bram Moolenaara47e05f2021-01-12 21:49:00 +0100727 type() type of a variable as a number
728 typename() type of a variable as text
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000729 islocked() check if a variable is locked
Bram Moolenaar214641f2017-03-05 17:04:09 +0100730 funcref() get a Funcref for a function reference
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000731 function() get a Funcref for a function name
732 getbufvar() get a variable value from a specific buffer
733 setbufvar() set a variable in a specific buffer
Bram Moolenaarc6249bb2006-04-15 20:25:09 +0000734 getwinvar() get a variable from specific window
Bram Moolenaar06b5d512010-05-22 15:37:44 +0200735 gettabvar() get a variable from specific tab page
Bram Moolenaarc6249bb2006-04-15 20:25:09 +0000736 gettabwinvar() get a variable from specific window & tab page
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000737 setwinvar() set a variable in a specific window
Bram Moolenaar06b5d512010-05-22 15:37:44 +0200738 settabvar() set a variable in a specific tab page
Bram Moolenaarc6249bb2006-04-15 20:25:09 +0000739 settabwinvar() set a variable in a specific window & tab page
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000740 garbagecollect() possibly free memory
741
Bram Moolenaara3f41662010-07-11 19:01:06 +0200742Cursor and mark position: *cursor-functions* *mark-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000743 col() column number of the cursor or a mark
744 virtcol() screen column of the cursor or a mark
745 line() line number of the cursor or mark
746 wincol() window column number of the cursor
747 winline() window line number of the cursor
748 cursor() position the cursor at a line/column
Bram Moolenaar8d043172014-01-23 14:24:41 +0100749 screencol() get screen column of the cursor
750 screenrow() get screen row of the cursor
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200751 screenpos() screen row and col of a text character
Bram Moolenaar822ff862014-06-12 21:46:14 +0200752 getcurpos() get position of the cursor
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000753 getpos() get position of cursor, mark, etc.
754 setpos() set position of cursor, mark, etc.
Bram Moolenaarcfb4b472020-05-31 15:41:57 +0200755 getmarklist() list of global/local marks
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000756 byte2line() get line number at a specific byte count
757 line2byte() byte count at a specific line
758 diff_filler() get the number of filler lines above a line
Bram Moolenaar8d043172014-01-23 14:24:41 +0100759 screenattr() get attribute at a screen line/row
760 screenchar() get character code at a screen line/row
Bram Moolenaar2912abb2019-03-29 14:16:42 +0100761 screenchars() get character codes at a screen line/row
762 screenstring() get string of characters at a screen line/row
Bram Moolenaar6f02b002021-01-10 20:22:54 +0100763 charcol() character number of the cursor or a mark
764 getcharpos() get character position of cursor, mark, etc.
765 setcharpos() set character position of cursor, mark, etc.
766 getcursorcharpos() get character position of the cursor
767 setcursorcharpos() set character position of the cursor
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000768
Bram Moolenaara3f41662010-07-11 19:01:06 +0200769Working with text in the current buffer: *text-functions*
Bram Moolenaar7c626922005-02-07 22:01:03 +0000770 getline() get a line or list of lines from the buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +0000771 setline() replace a line in the buffer
Bram Moolenaar7c626922005-02-07 22:01:03 +0000772 append() append line or list of lines in the buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +0000773 indent() indent of a specific line
774 cindent() indent according to C indenting
775 lispindent() indent according to Lisp indenting
776 nextnonblank() find next non-blank line
777 prevnonblank() find previous non-blank line
778 search() find a match for a pattern
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000779 searchpos() find a match for a pattern
Bram Moolenaarebacddb2020-06-04 15:22:21 +0200780 searchcount() get number of matches before/after the cursor
Bram Moolenaar071d4272004-06-13 20:20:40 +0000781 searchpair() find the other end of a start/skip/end
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000782 searchpairpos() find the other end of a start/skip/end
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000783 searchdecl() search for the declaration of a name
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200784 getcharsearch() return character search information
785 setcharsearch() set character search information
Bram Moolenaar071d4272004-06-13 20:20:40 +0000786
Bram Moolenaar931a2772019-07-04 16:54:54 +0200787Working with text in another buffer:
788 getbufline() get a list of lines from the specified buffer
789 setbufline() replace a line in the specified buffer
790 appendbufline() append a list of lines in the specified buffer
791 deletebufline() delete lines from a specified buffer
792
Bram Moolenaara3f41662010-07-11 19:01:06 +0200793 *system-functions* *file-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000794System functions and manipulation of files:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000795 glob() expand wildcards
796 globpath() expand wildcards in a number of directories
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200797 glob2regpat() convert a glob pattern into a search pattern
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000798 findfile() find a file in a list of directories
799 finddir() find a directory in a list of directories
Bram Moolenaar071d4272004-06-13 20:20:40 +0000800 resolve() find out where a shortcut points to
801 fnamemodify() modify a file name
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000802 pathshorten() shorten directory names in a path
803 simplify() simplify a path without changing its meaning
Bram Moolenaar071d4272004-06-13 20:20:40 +0000804 executable() check if an executable program exists
Bram Moolenaar7e38ea22014-04-05 22:55:53 +0200805 exepath() full path of an executable program
Bram Moolenaar071d4272004-06-13 20:20:40 +0000806 filereadable() check if a file can be read
807 filewritable() check if a file can be written to
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000808 getfperm() get the permissions of a file
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200809 setfperm() set the permissions of a file
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000810 getftype() get the kind of a file
Bram Moolenaar071d4272004-06-13 20:20:40 +0000811 isdirectory() check if a directory exists
Bram Moolenaar071d4272004-06-13 20:20:40 +0000812 getfsize() get the size of a file
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000813 getcwd() get the current working directory
Bram Moolenaar00aa0692019-04-27 20:37:57 +0200814 haslocaldir() check if current window used |:lcd| or |:tcd|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000815 tempname() get the name of a temporary file
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000816 mkdir() create a new directory
Bram Moolenaar1063f3d2019-05-07 22:06:52 +0200817 chdir() change current working directory
Bram Moolenaar071d4272004-06-13 20:20:40 +0000818 delete() delete a file
819 rename() rename a file
Bram Moolenaar7e38ea22014-04-05 22:55:53 +0200820 system() get the result of a shell command as a string
821 systemlist() get the result of a shell command as a list
Bram Moolenaar691ddee2019-05-09 14:52:41 +0200822 environ() get all environment variables
823 getenv() get one environment variable
824 setenv() set an environment variable
Bram Moolenaar071d4272004-06-13 20:20:40 +0000825 hostname() name of the system
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +0000826 readfile() read a file into a List of lines
Bram Moolenaarc423ad72021-01-13 20:38:03 +0100827 readblob() read a file into a Blob
Bram Moolenaar62e1bb42019-04-08 16:25:07 +0200828 readdir() get a List of file names in a directory
Bram Moolenaar6c9ba042020-06-01 16:09:41 +0200829 readdirex() get a List of file information in a directory
Bram Moolenaar314dd792019-02-03 15:27:20 +0100830 writefile() write a List of lines or Blob into a file
Bram Moolenaar071d4272004-06-13 20:20:40 +0000831
Bram Moolenaara3f41662010-07-11 19:01:06 +0200832Date and Time: *date-functions* *time-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000833 getftime() get last modification time of a file
834 localtime() get current time in seconds
835 strftime() convert time to a string
Bram Moolenaar10455d42019-11-21 15:36:18 +0100836 strptime() convert a date/time string to time
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000837 reltime() get the current or elapsed time accurately
838 reltimestr() convert reltime() result to a string
Bram Moolenaar03413f42016-04-12 21:07:15 +0200839 reltimefloat() convert reltime() result to a Float
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000840
Bram Moolenaara3f41662010-07-11 19:01:06 +0200841 *buffer-functions* *window-functions* *arg-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000842Buffers, windows and the argument list:
843 argc() number of entries in the argument list
844 argidx() current position in the argument list
Bram Moolenaar2d1fe052014-05-28 18:22:57 +0200845 arglistid() get id of the argument list
Bram Moolenaar071d4272004-06-13 20:20:40 +0000846 argv() get one entry from the argument list
Bram Moolenaar931a2772019-07-04 16:54:54 +0200847 bufadd() add a file to the list of buffers
Bram Moolenaar071d4272004-06-13 20:20:40 +0000848 bufexists() check if a buffer exists
849 buflisted() check if a buffer exists and is listed
Bram Moolenaar931a2772019-07-04 16:54:54 +0200850 bufload() ensure a buffer is loaded
Bram Moolenaar071d4272004-06-13 20:20:40 +0000851 bufloaded() check if a buffer exists and is loaded
852 bufname() get the name of a specific buffer
853 bufnr() get the buffer number of a specific buffer
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000854 tabpagebuflist() return List of buffers in a tab page
855 tabpagenr() get the number of a tab page
856 tabpagewinnr() like winnr() for a specified tab page
Bram Moolenaar071d4272004-06-13 20:20:40 +0000857 winnr() get the window number for the current window
Bram Moolenaar82af8712016-06-04 20:20:29 +0200858 bufwinid() get the window ID of a specific buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +0000859 bufwinnr() get the window number of a specific buffer
860 winbufnr() get the buffer number of a specific window
Bram Moolenaara3347722019-05-11 21:14:24 +0200861 listener_add() add a callback to listen to changes
Bram Moolenaar68e65602019-05-26 21:33:31 +0200862 listener_flush() invoke listener callbacks
Bram Moolenaara3347722019-05-11 21:14:24 +0200863 listener_remove() remove a listener callback
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200864 win_findbuf() find windows containing a buffer
865 win_getid() get window ID of a window
Bram Moolenaarebacddb2020-06-04 15:22:21 +0200866 win_gettype() get type of window
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200867 win_gotoid() go to window with ID
868 win_id2tabwin() get tab and window nr from window ID
869 win_id2win() get window nr from window ID
Bram Moolenaarebacddb2020-06-04 15:22:21 +0200870 win_splitmove() move window to a split of another window
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +0200871 getbufinfo() get a list with buffer information
872 gettabinfo() get a list with tab page information
873 getwininfo() get a list with window information
Bram Moolenaar07ad8162018-02-13 13:59:59 +0100874 getchangelist() get a list of change list entries
Bram Moolenaar4f505882018-02-10 21:06:32 +0100875 getjumplist() get a list of jump list entries
Bram Moolenaarfc65cab2018-08-28 22:58:02 +0200876 swapinfo() information about a swap file
Bram Moolenaarb730f0c2018-11-25 03:56:26 +0100877 swapname() get the swap file path of a buffer
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000878
Bram Moolenaara3f41662010-07-11 19:01:06 +0200879Command line: *command-line-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000880 getcmdline() get the current command line
881 getcmdpos() get position of the cursor in the command line
882 setcmdpos() set position of the cursor in the command line
883 getcmdtype() return the current command-line type
Bram Moolenaarfb539272014-08-22 19:21:47 +0200884 getcmdwintype() return the current command-line window type
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +0200885 getcompletion() list of command-line completion matches
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000886
Bram Moolenaara3f41662010-07-11 19:01:06 +0200887Quickfix and location lists: *quickfix-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000888 getqflist() list of quickfix errors
889 setqflist() modify a quickfix list
890 getloclist() list of location list items
891 setloclist() modify a location list
892
Bram Moolenaara3f41662010-07-11 19:01:06 +0200893Insert mode completion: *completion-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000894 complete() set found matches
895 complete_add() add to found matches
896 complete_check() check if completion should be aborted
Bram Moolenaarfd133322019-03-29 12:20:27 +0100897 complete_info() get current completion information
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000898 pumvisible() check if the popup menu is displayed
Bram Moolenaar5be4cee2019-09-27 19:34:08 +0200899 pum_getpos() position and size of popup menu if visible
Bram Moolenaar071d4272004-06-13 20:20:40 +0000900
Bram Moolenaara3f41662010-07-11 19:01:06 +0200901Folding: *folding-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000902 foldclosed() check for a closed fold at a specific line
903 foldclosedend() like foldclosed() but return the last line
904 foldlevel() check for the fold level at a specific line
905 foldtext() generate the line displayed for a closed fold
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000906 foldtextresult() get the text displayed for a closed fold
Bram Moolenaar071d4272004-06-13 20:20:40 +0000907
Bram Moolenaara3f41662010-07-11 19:01:06 +0200908Syntax and highlighting: *syntax-functions* *highlighting-functions*
Bram Moolenaar6ee10162007-07-26 20:58:42 +0000909 clearmatches() clear all matches defined by |matchadd()| and
910 the |:match| commands
911 getmatches() get all matches defined by |matchadd()| and
912 the |:match| commands
Bram Moolenaar071d4272004-06-13 20:20:40 +0000913 hlexists() check if a highlight group exists
914 hlID() get ID of a highlight group
915 synID() get syntax ID at a specific position
916 synIDattr() get a specific attribute of a syntax ID
917 synIDtrans() get translated syntax ID
Bram Moolenaar166af9b2010-11-16 20:34:40 +0100918 synstack() get list of syntax IDs at a specific position
Bram Moolenaar81af9252010-12-10 20:35:50 +0100919 synconcealed() get info about concealing
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000920 diff_hlID() get highlight ID for diff mode at a position
Bram Moolenaar6ee10162007-07-26 20:58:42 +0000921 matchadd() define a pattern to highlight (a "match")
Bram Moolenaarb3414592014-06-17 17:48:32 +0200922 matchaddpos() define a list of positions to highlight
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000923 matcharg() get info about |:match| arguments
Bram Moolenaar6ee10162007-07-26 20:58:42 +0000924 matchdelete() delete a match defined by |matchadd()| or a
925 |:match| command
926 setmatches() restore a list of matches saved by
927 |getmatches()|
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000928
Bram Moolenaara3f41662010-07-11 19:01:06 +0200929Spelling: *spell-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000930 spellbadword() locate badly spelled word at or after cursor
931 spellsuggest() return suggested spelling corrections
932 soundfold() return the sound-a-like equivalent of a word
Bram Moolenaar071d4272004-06-13 20:20:40 +0000933
Bram Moolenaara3f41662010-07-11 19:01:06 +0200934History: *history-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000935 histadd() add an item to a history
936 histdel() delete an item from a history
937 histget() get an item from a history
938 histnr() get highest index of a history list
939
Bram Moolenaara3f41662010-07-11 19:01:06 +0200940Interactive: *interactive-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000941 browse() put up a file requester
942 browsedir() put up a directory requester
Bram Moolenaar071d4272004-06-13 20:20:40 +0000943 confirm() let the user make a choice
944 getchar() get a character from the user
945 getcharmod() get modifiers for the last typed character
Bram Moolenaar09c6f262019-11-17 15:55:14 +0100946 getmousepos() get last known mouse position
Bram Moolenaarebacddb2020-06-04 15:22:21 +0200947 echoraw() output characters as-is
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000948 feedkeys() put characters in the typeahead queue
Bram Moolenaar071d4272004-06-13 20:20:40 +0000949 input() get a line from the user
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000950 inputlist() let the user pick an entry from a list
Bram Moolenaar071d4272004-06-13 20:20:40 +0000951 inputsecret() get a line from the user without showing it
952 inputdialog() get a line from the user in a dialog
Bram Moolenaar68b76a62005-03-25 21:53:48 +0000953 inputsave() save and clear typeahead
Bram Moolenaar071d4272004-06-13 20:20:40 +0000954 inputrestore() restore typeahead
955
Bram Moolenaara3f41662010-07-11 19:01:06 +0200956GUI: *gui-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000957 getfontname() get name of current font being used
Bram Moolenaarb5b75622018-03-09 22:22:21 +0100958 getwinpos() position of the Vim window
959 getwinposx() X position of the Vim window
960 getwinposy() Y position of the Vim window
Bram Moolenaar214641f2017-03-05 17:04:09 +0100961 balloon_show() set the balloon content
Bram Moolenaara2a80162017-11-21 23:09:50 +0100962 balloon_split() split a message for a balloon
Bram Moolenaar691ddee2019-05-09 14:52:41 +0200963 balloon_gettext() get the text in the balloon
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000964
Bram Moolenaara3f41662010-07-11 19:01:06 +0200965Vim server: *server-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000966 serverlist() return the list of server names
Bram Moolenaar01164a62017-11-02 22:58:42 +0100967 remote_startserver() run a server
Bram Moolenaar071d4272004-06-13 20:20:40 +0000968 remote_send() send command characters to a Vim server
969 remote_expr() evaluate an expression in a Vim server
970 server2client() send a reply to a client of a Vim server
971 remote_peek() check if there is a reply from a Vim server
972 remote_read() read a reply from a Vim server
973 foreground() move the Vim window to the foreground
974 remote_foreground() move the Vim server window to the foreground
975
Bram Moolenaara3f41662010-07-11 19:01:06 +0200976Window size and position: *window-size-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000977 winheight() get height of a specific window
978 winwidth() get width of a specific window
Bram Moolenaarf0b03c42017-12-17 17:17:07 +0100979 win_screenpos() get screen position of a window
Bram Moolenaarb730f0c2018-11-25 03:56:26 +0100980 winlayout() get layout of windows in a tab page
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000981 winrestcmd() return command to restore window sizes
982 winsaveview() get view of current window
983 winrestview() restore saved view of current window
984
Bram Moolenaar0eabd4d2020-03-15 16:13:53 +0100985Mappings and Menus: *mapping-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000986 hasmapto() check if a mapping exists
987 mapcheck() check if a matching mapping exists
988 maparg() get rhs of a mapping
Bram Moolenaarebacddb2020-06-04 15:22:21 +0200989 mapset() restore a mapping
Bram Moolenaar0eabd4d2020-03-15 16:13:53 +0100990 menu_info() get information about a menu item
Bram Moolenaar26402cb2013-02-20 21:26:00 +0100991 wildmenumode() check if the wildmode is active
992
Bram Moolenaar683fa182015-11-30 21:38:24 +0100993Testing: *test-functions*
Bram Moolenaare18c0b32016-03-20 21:08:34 +0100994 assert_equal() assert that two expressions values are equal
Bram Moolenaarb730f0c2018-11-25 03:56:26 +0100995 assert_equalfile() assert that two file contents are equal
Bram Moolenaar03413f42016-04-12 21:07:15 +0200996 assert_notequal() assert that two expressions values are not equal
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +0200997 assert_inrange() assert that an expression is inside a range
Bram Moolenaar7db8f6f2016-03-29 23:12:46 +0200998 assert_match() assert that a pattern matches the value
Bram Moolenaar03413f42016-04-12 21:07:15 +0200999 assert_notmatch() assert that a pattern does not match the value
Bram Moolenaar683fa182015-11-30 21:38:24 +01001000 assert_false() assert that an expression is false
1001 assert_true() assert that an expression is true
Bram Moolenaare18c0b32016-03-20 21:08:34 +01001002 assert_exception() assert that a command throws an exception
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01001003 assert_beeps() assert that a command beeps
1004 assert_fails() assert that a command fails
Bram Moolenaar3c2881d2017-03-21 19:18:29 +01001005 assert_report() report a test failure
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001006 test_alloc_fail() make memory allocation fail
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +02001007 test_autochdir() enable 'autochdir' during startup
Bram Moolenaar036986f2017-03-16 17:41:02 +01001008 test_override() test with Vim internal overrides
1009 test_garbagecollect_now() free memory right now
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001010 test_garbagecollect_soon() set a flag to free memory soon
Bram Moolenaar68e65602019-05-26 21:33:31 +02001011 test_getvalue() get value of an internal variable
Bram Moolenaar214641f2017-03-05 17:04:09 +01001012 test_ignore_error() ignore a specific error message
Bram Moolenaar314dd792019-02-03 15:27:20 +01001013 test_null_blob() return a null Blob
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001014 test_null_channel() return a null Channel
1015 test_null_dict() return a null Dict
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001016 test_null_function() return a null Funcref
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001017 test_null_job() return a null Job
1018 test_null_list() return a null List
1019 test_null_partial() return a null Partial function
1020 test_null_string() return a null String
Bram Moolenaar214641f2017-03-05 17:04:09 +01001021 test_settime() set the time Vim uses internally
Bram Moolenaarbb8476b2019-05-04 15:47:48 +02001022 test_setmouse() set the mouse position
Bram Moolenaarb730f0c2018-11-25 03:56:26 +01001023 test_feedinput() add key sequence to input buffer
1024 test_option_not_set() reset flag indicating option was set
1025 test_scrollbar() simulate scrollbar movement in the GUI
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001026 test_refcount() return an expression's reference count
1027 test_srand_seed() set the seed value for srand()
1028 test_unknown() return a value with unknown type
1029 test_void() return a value with void type
Bram Moolenaar683fa182015-11-30 21:38:24 +01001030
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001031Inter-process communication: *channel-functions*
Bram Moolenaar51628222016-12-01 23:03:28 +01001032 ch_canread() check if there is something to read
Bram Moolenaar681baaf2016-02-04 20:57:07 +01001033 ch_open() open a channel
1034 ch_close() close a channel
Bram Moolenaar64d8e252016-09-06 22:12:34 +02001035 ch_close_in() close the in part of a channel
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001036 ch_read() read a message from a channel
Bram Moolenaard09091d2019-01-17 16:07:22 +01001037 ch_readblob() read a Blob from a channel
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001038 ch_readraw() read a raw message from a channel
Bram Moolenaar681baaf2016-02-04 20:57:07 +01001039 ch_sendexpr() send a JSON message over a channel
1040 ch_sendraw() send a raw message over a channel
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001041 ch_evalexpr() evaluate an expression over channel
1042 ch_evalraw() evaluate a raw string over channel
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001043 ch_status() get status of a channel
1044 ch_getbufnr() get the buffer number of a channel
1045 ch_getjob() get the job associated with a channel
1046 ch_info() get channel information
1047 ch_log() write a message in the channel log file
1048 ch_logfile() set the channel log file
1049 ch_setoptions() set the options for a channel
Bram Moolenaara02a5512016-06-17 12:48:11 +02001050 json_encode() encode an expression to a JSON string
1051 json_decode() decode a JSON string to Vim types
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001052 js_encode() encode an expression to a JSON string
1053 js_decode() decode a JSON string to Vim types
1054
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001055Jobs: *job-functions*
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001056 job_start() start a job
1057 job_stop() stop a job
1058 job_status() get the status of a job
1059 job_getchannel() get the channel used by a job
1060 job_info() get information about a job
1061 job_setoptions() set options for a job
1062
Bram Moolenaar162b7142018-12-21 15:17:36 +01001063Signs: *sign-functions*
1064 sign_define() define or update a sign
1065 sign_getdefined() get a list of defined signs
1066 sign_getplaced() get a list of placed signs
Bram Moolenaar6b7b7192019-01-11 13:42:41 +01001067 sign_jump() jump to a sign
Bram Moolenaar162b7142018-12-21 15:17:36 +01001068 sign_place() place a sign
Bram Moolenaar809ce4d2019-07-13 21:21:40 +02001069 sign_placelist() place a list of signs
Bram Moolenaar162b7142018-12-21 15:17:36 +01001070 sign_undefine() undefine a sign
1071 sign_unplace() unplace a sign
Bram Moolenaar809ce4d2019-07-13 21:21:40 +02001072 sign_unplacelist() unplace a list of signs
Bram Moolenaar162b7142018-12-21 15:17:36 +01001073
Bram Moolenaarc572da52017-08-27 16:52:01 +02001074Terminal window: *terminal-functions*
1075 term_start() open a terminal window and run a job
1076 term_list() get the list of terminal buffers
1077 term_sendkeys() send keystrokes to a terminal
1078 term_wait() wait for screen to be updated
1079 term_getjob() get the job associated with a terminal
1080 term_scrape() get row of a terminal screen
1081 term_getline() get a line of text from a terminal
1082 term_getattr() get the value of attribute {what}
1083 term_getcursor() get the cursor position of a terminal
1084 term_getscrolled() get the scroll count of a terminal
1085 term_getaltscreen() get the alternate screen flag
1086 term_getsize() get the size of a terminal
1087 term_getstatus() get the status of a terminal
1088 term_gettitle() get the title of a terminal
1089 term_gettty() get the tty name of a terminal
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02001090 term_setansicolors() set 16 ANSI colors, used for GUI
1091 term_getansicolors() get 16 ANSI colors, used for GUI
Bram Moolenaarb730f0c2018-11-25 03:56:26 +01001092 term_dumpdiff() display difference between two screen dumps
1093 term_dumpload() load a terminal screen dump in a window
1094 term_dumpwrite() dump contents of a terminal screen to a file
1095 term_setkill() set signal to stop job in a terminal
1096 term_setrestore() set command to restore a terminal
1097 term_setsize() set the size of a terminal
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001098 term_setapi() set terminal JSON API function name prefix
Bram Moolenaarc572da52017-08-27 16:52:01 +02001099
Bram Moolenaar931a2772019-07-04 16:54:54 +02001100Popup window: *popup-window-functions*
1101 popup_create() create popup centered in the screen
1102 popup_atcursor() create popup just above the cursor position,
1103 closes when the cursor moves away
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02001104 popup_beval() at the position indicated by v:beval_
1105 variables, closes when the mouse moves away
Bram Moolenaar931a2772019-07-04 16:54:54 +02001106 popup_notification() show a notification for three seconds
1107 popup_dialog() create popup centered with padding and border
1108 popup_menu() prompt for selecting an item from a list
1109 popup_hide() hide a popup temporarily
1110 popup_show() show a previously hidden popup
1111 popup_move() change the position and size of a popup
1112 popup_setoptions() override options of a popup
1113 popup_settext() replace the popup buffer contents
1114 popup_close() close one popup
1115 popup_clear() close all popups
1116 popup_filter_menu() select from a list of items
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001117 popup_filter_yesno() block until 'y' or 'n' is pressed
Bram Moolenaar931a2772019-07-04 16:54:54 +02001118 popup_getoptions() get current options for a popup
1119 popup_getpos() get actual position and size of a popup
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001120 popup_findinfo() get window ID for popup info window
1121 popup_findpreview() get window ID for popup preview window
1122 popup_list() get list of all popup window IDs
1123 popup_locate() get popup window ID from its screen position
Bram Moolenaar931a2772019-07-04 16:54:54 +02001124
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001125Timers: *timer-functions*
1126 timer_start() create a timer
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02001127 timer_pause() pause or unpause a timer
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001128 timer_stop() stop a timer
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02001129 timer_stopall() stop all timers
1130 timer_info() get information about timers
Bram Moolenaar298b4402016-01-28 22:38:53 +01001131
Bram Moolenaarb730f0c2018-11-25 03:56:26 +01001132Tags: *tag-functions*
1133 taglist() get list of matching tags
1134 tagfiles() get a list of tags files
1135 gettagstack() get the tag stack of a window
1136 settagstack() modify the tag stack of a window
1137
1138Prompt Buffer: *promptbuffer-functions*
Bram Moolenaar077cc7a2020-09-04 16:35:35 +02001139 prompt_getprompt() get the effective prompt text for a buffer
Bram Moolenaarb730f0c2018-11-25 03:56:26 +01001140 prompt_setcallback() set prompt callback for a buffer
1141 prompt_setinterrupt() set interrupt callback for a buffer
1142 prompt_setprompt() set the prompt text for a buffer
1143
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001144Text Properties: *text-property-functions*
1145 prop_add() attach a property at a position
1146 prop_clear() remove all properties from a line or lines
1147 prop_find() search for a property
1148 prop_list() return a list of all properties in a line
1149 prop_remove() remove a property from a line
1150 prop_type_add() add/define a property type
1151 prop_type_change() change properties of a type
1152 prop_type_delete() remove a text property type
1153 prop_type_get() return the properties of a type
1154 prop_type_list() return a list of all property types
1155
1156Sound: *sound-functions*
1157 sound_clear() stop playing all sounds
1158 sound_playevent() play an event's sound
1159 sound_playfile() play a sound file
1160 sound_stop() stop playing a sound
1161
Bram Moolenaar26402cb2013-02-20 21:26:00 +01001162Various: *various-functions*
1163 mode() get current editing mode
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001164 state() get current busy state
Bram Moolenaar26402cb2013-02-20 21:26:00 +01001165 visualmode() last visual mode used
Bram Moolenaar071d4272004-06-13 20:20:40 +00001166 exists() check if a variable, function, etc. exists
1167 has() check if a feature is supported in Vim
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001168 changenr() return number of most recent change
Bram Moolenaar071d4272004-06-13 20:20:40 +00001169 cscope_connection() check if a cscope connection exists
1170 did_filetype() check if a FileType autocommand was used
1171 eventhandler() check if invoked by an event handler
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00001172 getpid() get process ID of Vim
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001173 getimstatus() check if IME status is active
1174 interrupt() interrupt script execution
1175 windowsversion() get MS-Windows version
Bram Moolenaar0c0eddd2020-06-13 15:47:25 +02001176 terminalprops() properties of the terminal
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001177
Bram Moolenaar071d4272004-06-13 20:20:40 +00001178 libcall() call a function in an external library
1179 libcallnr() idem, returning a number
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001180
Bram Moolenaar8d043172014-01-23 14:24:41 +01001181 undofile() get the name of the undo file
1182 undotree() return the state of the undo tree
1183
Bram Moolenaar071d4272004-06-13 20:20:40 +00001184 getreg() get contents of a register
Bram Moolenaarbb861e22020-06-07 18:16:36 +02001185 getreginfo() get information about a register
Bram Moolenaar071d4272004-06-13 20:20:40 +00001186 getregtype() get type of a register
1187 setreg() set contents and type of a register
Bram Moolenaar0b6d9112018-05-22 20:35:17 +02001188 reg_executing() return the name of the register being executed
1189 reg_recording() return the name of the register being recorded
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001190
Bram Moolenaar8d043172014-01-23 14:24:41 +01001191 shiftwidth() effective value of 'shiftwidth'
1192
Bram Moolenaar063b9d12016-07-09 20:21:48 +02001193 wordcount() get byte/word/char count of buffer
1194
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001195 luaeval() evaluate |Lua| expression
Bram Moolenaar7e506b62010-01-19 15:55:06 +01001196 mzeval() evaluate |MzScheme| expression
Bram Moolenaare9b892e2016-01-17 21:15:58 +01001197 perleval() evaluate Perl expression (|+perl|)
Bram Moolenaar8d043172014-01-23 14:24:41 +01001198 py3eval() evaluate Python expression (|+python3|)
1199 pyeval() evaluate Python expression (|+python|)
Bram Moolenaar690afe12017-01-28 18:34:47 +01001200 pyxeval() evaluate |python_x| expression
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001201 rubyeval() evaluate |Ruby| expression
1202
Bram Moolenaar9d87a372018-12-18 21:41:50 +01001203 debugbreak() interrupt a program being debugged
Bram Moolenaar7e506b62010-01-19 15:55:06 +01001204
Bram Moolenaar071d4272004-06-13 20:20:40 +00001205==============================================================================
1206*41.7* Defining a function
1207
1208Vim enables you to define your own functions. The basic function declaration
1209begins as follows: >
1210
1211 :function {name}({var1}, {var2}, ...)
1212 : {body}
1213 :endfunction
1214<
1215 Note:
1216 Function names must begin with a capital letter.
1217
1218Let's define a short function to return the smaller of two numbers. It starts
1219with this line: >
1220
1221 :function Min(num1, num2)
1222
1223This tells Vim that the function is named "Min" and it takes two arguments:
1224"num1" and "num2".
1225 The first thing you need to do is to check to see which number is smaller:
1226 >
1227 : if a:num1 < a:num2
1228
1229The special prefix "a:" tells Vim that the variable is a function argument.
1230Let's assign the variable "smaller" the value of the smallest number: >
1231
1232 : if a:num1 < a:num2
1233 : let smaller = a:num1
1234 : else
1235 : let smaller = a:num2
1236 : endif
1237
1238The variable "smaller" is a local variable. Variables used inside a function
1239are local unless prefixed by something like "g:", "a:", or "s:".
1240
1241 Note:
1242 To access a global variable from inside a function you must prepend
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00001243 "g:" to it. Thus "g:today" inside a function is used for the global
1244 variable "today", and "today" is another variable, local to the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001245 function.
1246
1247You now use the ":return" statement to return the smallest number to the user.
1248Finally, you end the function: >
1249
1250 : return smaller
1251 :endfunction
1252
1253The complete function definition is as follows: >
1254
1255 :function Min(num1, num2)
1256 : if a:num1 < a:num2
1257 : let smaller = a:num1
1258 : else
1259 : let smaller = a:num2
1260 : endif
1261 : return smaller
1262 :endfunction
1263
Bram Moolenaar7c626922005-02-07 22:01:03 +00001264For people who like short functions, this does the same thing: >
1265
1266 :function Min(num1, num2)
1267 : if a:num1 < a:num2
1268 : return a:num1
1269 : endif
1270 : return a:num2
1271 :endfunction
1272
Bram Moolenaard1f56e62006-02-22 21:25:37 +00001273A user defined function is called in exactly the same way as a built-in
Bram Moolenaar071d4272004-06-13 20:20:40 +00001274function. Only the name is different. The Min function can be used like
1275this: >
1276
1277 :echo Min(5, 8)
1278
1279Only now will the function be executed and the lines be interpreted by Vim.
1280If there are mistakes, like using an undefined variable or function, you will
1281now get an error message. When defining the function these errors are not
1282detected.
1283
1284When a function reaches ":endfunction" or ":return" is used without an
1285argument, the function returns zero.
1286
1287To redefine a function that already exists, use the ! for the ":function"
1288command: >
1289
1290 :function! Min(num1, num2, num3)
1291
1292
1293USING A RANGE
1294
1295The ":call" command can be given a line range. This can have one of two
1296meanings. When a function has been defined with the "range" keyword, it will
1297take care of the line range itself.
1298 The function will be passed the variables "a:firstline" and "a:lastline".
1299These will have the line numbers from the range the function was called with.
1300Example: >
1301
1302 :function Count_words() range
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00001303 : let lnum = a:firstline
1304 : let n = 0
1305 : while lnum <= a:lastline
1306 : let n = n + len(split(getline(lnum)))
1307 : let lnum = lnum + 1
Bram Moolenaar071d4272004-06-13 20:20:40 +00001308 : endwhile
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001309 : echo "found " .. n .. " words"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001310 :endfunction
1311
1312You can call this function with: >
1313
1314 :10,30call Count_words()
1315
1316It will be executed once and echo the number of words.
1317 The other way to use a line range is by defining a function without the
1318"range" keyword. The function will be called once for every line in the
1319range, with the cursor in that line. Example: >
1320
1321 :function Number()
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001322 : echo "line " .. line(".") .. " contains: " .. getline(".")
Bram Moolenaar071d4272004-06-13 20:20:40 +00001323 :endfunction
1324
1325If you call this function with: >
1326
1327 :10,15call Number()
1328
1329The function will be called six times.
1330
1331
1332VARIABLE NUMBER OF ARGUMENTS
1333
1334Vim enables you to define functions that have a variable number of arguments.
1335The following command, for instance, defines a function that must have 1
1336argument (start) and can have up to 20 additional arguments: >
1337
1338 :function Show(start, ...)
1339
1340The variable "a:1" contains the first optional argument, "a:2" the second, and
1341so on. The variable "a:0" contains the number of extra arguments.
1342 For example: >
1343
1344 :function Show(start, ...)
1345 : echohl Title
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001346 : echo "start is " .. a:start
Bram Moolenaar071d4272004-06-13 20:20:40 +00001347 : echohl None
1348 : let index = 1
1349 : while index <= a:0
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001350 : echo " Arg " .. index .. " is " .. a:{index}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001351 : let index = index + 1
1352 : endwhile
1353 : echo ""
1354 :endfunction
1355
1356This uses the ":echohl" command to specify the highlighting used for the
1357following ":echo" command. ":echohl None" stops it again. The ":echon"
1358command works like ":echo", but doesn't output a line break.
1359
Bram Moolenaar7c626922005-02-07 22:01:03 +00001360You can also use the a:000 variable, it is a List of all the "..." arguments.
1361See |a:000|.
1362
Bram Moolenaar071d4272004-06-13 20:20:40 +00001363
1364LISTING FUNCTIONS
1365
1366The ":function" command lists the names and arguments of all user-defined
1367functions: >
1368
1369 :function
1370< function Show(start, ...) ~
1371 function GetVimIndent() ~
1372 function SetSyn(name) ~
1373
1374To see what a function does, use its name as an argument for ":function": >
1375
1376 :function SetSyn
1377< 1 if &syntax == '' ~
1378 2 let &syntax = a:name ~
1379 3 endif ~
1380 endfunction ~
1381
1382
1383DEBUGGING
1384
1385The line number is useful for when you get an error message or when debugging.
1386See |debug-scripts| about debugging mode.
1387 You can also set the 'verbose' option to 12 or higher to see all function
1388calls. Set it to 15 or higher to see every executed line.
1389
1390
1391DELETING A FUNCTION
1392
1393To delete the Show() function: >
1394
1395 :delfunction Show
1396
1397You get an error when the function doesn't exist.
1398
Bram Moolenaar7c626922005-02-07 22:01:03 +00001399
1400FUNCTION REFERENCES
1401
1402Sometimes it can be useful to have a variable point to one function or
1403another. You can do it with the function() function. It turns the name of a
1404function into a reference: >
1405
1406 :let result = 0 " or 1
1407 :function! Right()
1408 : return 'Right!'
1409 :endfunc
1410 :function! Wrong()
1411 : return 'Wrong!'
1412 :endfunc
1413 :
1414 :if result == 1
1415 : let Afunc = function('Right')
1416 :else
1417 : let Afunc = function('Wrong')
1418 :endif
1419 :echo call(Afunc, [])
1420< Wrong! ~
1421
1422Note that the name of a variable that holds a function reference must start
1423with a capital. Otherwise it could be confused with the name of a builtin
1424function.
1425 The way to invoke a function that a variable refers to is with the call()
1426function. Its first argument is the function reference, the second argument
1427is a List with arguments.
1428
1429Function references are most useful in combination with a Dictionary, as is
1430explained in the next section.
1431
Bram Moolenaar071d4272004-06-13 20:20:40 +00001432==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00001433*41.8* Lists and Dictionaries
1434
1435So far we have used the basic types String and Number. Vim also supports two
1436composite types: List and Dictionary.
1437
1438A List is an ordered sequence of things. The things can be any kind of value,
1439thus you can make a List of numbers, a List of Lists and even a List of mixed
1440items. To create a List with three strings: >
1441
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001442 :let alist = ['aap', 'mies', 'noot']
Bram Moolenaar7c626922005-02-07 22:01:03 +00001443
1444The List items are enclosed in square brackets and separated by commas. To
1445create an empty List: >
1446
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001447 :let alist = []
Bram Moolenaar7c626922005-02-07 22:01:03 +00001448
1449You can add items to a List with the add() function: >
1450
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001451 :let alist = []
Bram Moolenaar7c626922005-02-07 22:01:03 +00001452 :call add(alist, 'foo')
1453 :call add(alist, 'bar')
1454 :echo alist
1455< ['foo', 'bar'] ~
1456
1457List concatenation is done with +: >
1458
1459 :echo alist + ['foo', 'bar']
1460< ['foo', 'bar', 'foo', 'bar'] ~
1461
1462Or, if you want to extend a List directly: >
1463
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001464 :let alist = ['one']
Bram Moolenaar7c626922005-02-07 22:01:03 +00001465 :call extend(alist, ['two', 'three'])
1466 :echo alist
1467< ['one', 'two', 'three'] ~
1468
1469Notice that using add() will have a different effect: >
1470
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001471 :let alist = ['one']
Bram Moolenaar7c626922005-02-07 22:01:03 +00001472 :call add(alist, ['two', 'three'])
1473 :echo alist
1474< ['one', ['two', 'three']] ~
1475
1476The second argument of add() is added as a single item.
1477
1478
1479FOR LOOP
1480
1481One of the nice things you can do with a List is iterate over it: >
1482
1483 :let alist = ['one', 'two', 'three']
1484 :for n in alist
1485 : echo n
1486 :endfor
1487< one ~
1488 two ~
1489 three ~
1490
1491This will loop over each element in List "alist", assigning the value to
1492variable "n". The generic form of a for loop is: >
1493
1494 :for {varname} in {listexpression}
1495 : {commands}
1496 :endfor
1497
1498To loop a certain number of times you need a List of a specific length. The
1499range() function creates one for you: >
1500
1501 :for a in range(3)
1502 : echo a
1503 :endfor
1504< 0 ~
1505 1 ~
1506 2 ~
1507
1508Notice that the first item of the List that range() produces is zero, thus the
1509last item is one less than the length of the list.
1510 You can also specify the maximum value, the stride and even go backwards: >
1511
1512 :for a in range(8, 4, -2)
1513 : echo a
1514 :endfor
1515< 8 ~
1516 6 ~
1517 4 ~
1518
1519A more useful example, looping over lines in the buffer: >
1520
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001521 :for line in getline(1, 20)
1522 : if line =~ "Date: "
1523 : echo matchstr(line, 'Date: \zs.*')
1524 : endif
1525 :endfor
Bram Moolenaar7c626922005-02-07 22:01:03 +00001526
1527This looks into lines 1 to 20 (inclusive) and echoes any date found in there.
1528
1529
1530DICTIONARIES
1531
1532A Dictionary stores key-value pairs. You can quickly lookup a value if you
1533know the key. A Dictionary is created with curly braces: >
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001534
Bram Moolenaar7c626922005-02-07 22:01:03 +00001535 :let uk2nl = {'one': 'een', 'two': 'twee', 'three': 'drie'}
1536
Bram Moolenaar4399ef42005-02-12 14:29:27 +00001537Now you can lookup words by putting the key in square brackets: >
Bram Moolenaar7c626922005-02-07 22:01:03 +00001538
1539 :echo uk2nl['two']
1540< twee ~
1541
1542The generic form for defining a Dictionary is: >
1543
1544 {<key> : <value>, ...}
1545
1546An empty Dictionary is one without any keys: >
1547
1548 {}
1549
1550The possibilities with Dictionaries are numerous. There are various functions
1551for them as well. For example, you can obtain a list of the keys and loop
1552over them: >
1553
1554 :for key in keys(uk2nl)
1555 : echo key
1556 :endfor
1557< three ~
1558 one ~
1559 two ~
1560
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00001561You will notice the keys are not ordered. You can sort the list to get a
Bram Moolenaar7c626922005-02-07 22:01:03 +00001562specific order: >
1563
1564 :for key in sort(keys(uk2nl))
1565 : echo key
1566 :endfor
1567< one ~
1568 three ~
1569 two ~
1570
1571But you can never get back the order in which items are defined. For that you
1572need to use a List, it stores items in an ordered sequence.
1573
1574
1575DICTIONARY FUNCTIONS
1576
1577The items in a Dictionary can normally be obtained with an index in square
1578brackets: >
1579
1580 :echo uk2nl['one']
1581< een ~
1582
1583A method that does the same, but without so many punctuation characters: >
1584
1585 :echo uk2nl.one
1586< een ~
1587
1588This only works for a key that is made of ASCII letters, digits and the
1589underscore. You can also assign a new value this way: >
1590
1591 :let uk2nl.four = 'vier'
1592 :echo uk2nl
1593< {'three': 'drie', 'four': 'vier', 'one': 'een', 'two': 'twee'} ~
1594
1595And now for something special: you can directly define a function and store a
1596reference to it in the dictionary: >
1597
1598 :function uk2nl.translate(line) dict
1599 : return join(map(split(a:line), 'get(self, v:val, "???")'))
1600 :endfunction
1601
1602Let's first try it out: >
1603
1604 :echo uk2nl.translate('three two five one')
1605< drie twee ??? een ~
1606
1607The first special thing you notice is the "dict" at the end of the ":function"
1608line. This marks the function as being used from a Dictionary. The "self"
1609local variable will then refer to that Dictionary.
1610 Now let's break up the complicated return command: >
1611
1612 split(a:line)
1613
Bram Moolenaar00654022011-02-25 14:42:19 +01001614The split() function takes a string, chops it into whitespace separated words
Bram Moolenaar7c626922005-02-07 22:01:03 +00001615and returns a list with these words. Thus in the example it returns: >
1616
1617 :echo split('three two five one')
1618< ['three', 'two', 'five', 'one'] ~
1619
1620This list is the first argument to the map() function. This will go through
1621the list, evaluating its second argument with "v:val" set to the value of each
1622item. This is a shortcut to using a for loop. This command: >
1623
1624 :let alist = map(split(a:line), 'get(self, v:val, "???")')
1625
1626Is equivalent to: >
1627
1628 :let alist = split(a:line)
1629 :for idx in range(len(alist))
1630 : let alist[idx] = get(self, alist[idx], "???")
1631 :endfor
1632
1633The get() function checks if a key is present in a Dictionary. If it is, then
1634the value is retrieved. If it isn't, then the default value is returned, in
Bram Moolenaar4399ef42005-02-12 14:29:27 +00001635the example it's '???'. This is a convenient way to handle situations where a
Bram Moolenaar7c626922005-02-07 22:01:03 +00001636key may not be present and you don't want an error message.
1637
1638The join() function does the opposite of split(): it joins together a list of
1639words, putting a space in between.
1640 This combination of split(), map() and join() is a nice way to filter a line
1641of words in a very compact way.
1642
1643
1644OBJECT ORIENTED PROGRAMMING
1645
1646Now that you can put both values and functions in a Dictionary, you can
1647actually use a Dictionary like an object.
1648 Above we used a Dictionary for translating Dutch to English. We might want
1649to do the same for other languages. Let's first make an object (aka
1650Dictionary) that has the translate function, but no words to translate: >
1651
1652 :let transdict = {}
1653 :function transdict.translate(line) dict
1654 : return join(map(split(a:line), 'get(self.words, v:val, "???")'))
1655 :endfunction
1656
1657It's slightly different from the function above, using 'self.words' to lookup
1658word translations. But we don't have a self.words. Thus you could call this
1659an abstract class.
1660
1661Now we can instantiate a Dutch translation object: >
1662
1663 :let uk2nl = copy(transdict)
1664 :let uk2nl.words = {'one': 'een', 'two': 'twee', 'three': 'drie'}
1665 :echo uk2nl.translate('three one')
1666< drie een ~
1667
1668And a German translator: >
1669
1670 :let uk2de = copy(transdict)
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001671 :let uk2de.words = {'one': 'eins', 'two': 'zwei', 'three': 'drei'}
Bram Moolenaar7c626922005-02-07 22:01:03 +00001672 :echo uk2de.translate('three one')
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001673< drei eins ~
Bram Moolenaar7c626922005-02-07 22:01:03 +00001674
1675You see that the copy() function is used to make a copy of the "transdict"
1676Dictionary and then the copy is changed to add the words. The original
1677remains the same, of course.
1678
1679Now you can go one step further, and use your preferred translator: >
1680
1681 :if $LANG =~ "de"
1682 : let trans = uk2de
1683 :else
1684 : let trans = uk2nl
1685 :endif
1686 :echo trans.translate('one two three')
1687< een twee drie ~
1688
1689Here "trans" refers to one of the two objects (Dictionaries). No copy is
1690made. More about List and Dictionary identity can be found at |list-identity|
1691and |dict-identity|.
1692
1693Now you might use a language that isn't supported. You can overrule the
1694translate() function to do nothing: >
1695
1696 :let uk2uk = copy(transdict)
1697 :function! uk2uk.translate(line)
1698 : return a:line
1699 :endfunction
1700 :echo uk2uk.translate('three one wladiwostok')
1701< three one wladiwostok ~
1702
1703Notice that a ! was used to overwrite the existing function reference. Now
1704use "uk2uk" when no recognized language is found: >
1705
1706 :if $LANG =~ "de"
1707 : let trans = uk2de
1708 :elseif $LANG =~ "nl"
1709 : let trans = uk2nl
1710 :else
1711 : let trans = uk2uk
1712 :endif
1713 :echo trans.translate('one two three')
1714< one two three ~
1715
1716For further reading see |Lists| and |Dictionaries|.
1717
1718==============================================================================
1719*41.9* Exceptions
Bram Moolenaar071d4272004-06-13 20:20:40 +00001720
1721Let's start with an example: >
1722
1723 :try
1724 : read ~/templates/pascal.tmpl
1725 :catch /E484:/
1726 : echo "Sorry, the Pascal template file cannot be found."
1727 :endtry
1728
1729The ":read" command will fail if the file does not exist. Instead of
1730generating an error message, this code catches the error and gives the user a
Bram Moolenaar00654022011-02-25 14:42:19 +01001731nice message.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001732
1733For the commands in between ":try" and ":endtry" errors are turned into
1734exceptions. An exception is a string. In the case of an error the string
1735contains the error message. And every error message has a number. In this
1736case, the error we catch contains "E484:". This number is guaranteed to stay
1737the same (the text may change, e.g., it may be translated).
1738
1739When the ":read" command causes another error, the pattern "E484:" will not
1740match in it. Thus this exception will not be caught and result in the usual
1741error message.
1742
1743You might be tempted to do this: >
1744
1745 :try
1746 : read ~/templates/pascal.tmpl
1747 :catch
1748 : echo "Sorry, the Pascal template file cannot be found."
1749 :endtry
1750
1751This means all errors are caught. But then you will not see errors that are
1752useful, such as "E21: Cannot make changes, 'modifiable' is off".
1753
1754Another useful mechanism is the ":finally" command: >
1755
1756 :let tmp = tempname()
1757 :try
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001758 : exe ".,$write " .. tmp
1759 : exe "!filter " .. tmp
Bram Moolenaar071d4272004-06-13 20:20:40 +00001760 : .,$delete
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001761 : exe "$read " .. tmp
Bram Moolenaar071d4272004-06-13 20:20:40 +00001762 :finally
1763 : call delete(tmp)
1764 :endtry
1765
1766This filters the lines from the cursor until the end of the file through the
1767"filter" command, which takes a file name argument. No matter if the
1768filtering works, something goes wrong in between ":try" and ":finally" or the
1769user cancels the filtering by pressing CTRL-C, the "call delete(tmp)" is
1770always executed. This makes sure you don't leave the temporary file behind.
1771
1772More information about exception handling can be found in the reference
1773manual: |exception-handling|.
1774
1775==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00001776*41.10* Various remarks
Bram Moolenaar071d4272004-06-13 20:20:40 +00001777
1778Here is a summary of items that apply to Vim scripts. They are also mentioned
1779elsewhere, but form a nice checklist.
1780
1781The end-of-line character depends on the system. For Unix a single <NL>
Bram Moolenaar4072ba52020-12-23 13:56:35 +01001782character is used. For MS-Windows and the like, <CR><NL> is used. This is
Bram Moolenaar6f345a12019-12-17 21:27:18 +01001783important when using mappings that end in a <CR>. See |:source_crnl|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001784
1785
1786WHITE SPACE
1787
1788Blank lines are allowed and ignored.
1789
1790Leading whitespace characters (blanks and TABs) are always ignored. The
Bram Moolenaar214641f2017-03-05 17:04:09 +01001791whitespaces between parameters (e.g. between the "set" and the "cpoptions" in
Bram Moolenaar071d4272004-06-13 20:20:40 +00001792the example below) are reduced to one blank character and plays the role of a
1793separator, the whitespaces after the last (visible) character may or may not
1794be ignored depending on the situation, see below.
1795
1796For a ":set" command involving the "=" (equal) sign, such as in: >
1797
1798 :set cpoptions =aABceFst
1799
1800the whitespace immediately before the "=" sign is ignored. But there can be
1801no whitespace after the "=" sign!
1802
1803To include a whitespace character in the value of an option, it must be
1804escaped by a "\" (backslash) as in the following example: >
1805
1806 :set tags=my\ nice\ file
1807
Bram Moolenaar00654022011-02-25 14:42:19 +01001808The same example written as: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001809
1810 :set tags=my nice file
1811
1812will issue an error, because it is interpreted as: >
1813
1814 :set tags=my
1815 :set nice
1816 :set file
1817
1818
1819COMMENTS
1820
1821The character " (the double quote mark) starts a comment. Everything after
1822and including this character until the end-of-line is considered a comment and
1823is ignored, except for commands that don't consider comments, as shown in
1824examples below. A comment can start on any character position on the line.
1825
1826There is a little "catch" with comments for some commands. Examples: >
1827
1828 :abbrev dev development " shorthand
1829 :map <F3> o#include " insert include
1830 :execute cmd " do it
1831 :!ls *.c " list C files
1832
1833The abbreviation 'dev' will be expanded to 'development " shorthand'. The
1834mapping of <F3> will actually be the whole line after the 'o# ....' including
1835the '" insert include'. The "execute" command will give an error. The "!"
1836command will send everything after it to the shell, causing an error for an
1837unmatched '"' character.
1838 There can be no comment after ":map", ":abbreviate", ":execute" and "!"
1839commands (there are a few more commands with this restriction). For the
1840":map", ":abbreviate" and ":execute" commands there is a trick: >
1841
1842 :abbrev dev development|" shorthand
1843 :map <F3> o#include|" insert include
1844 :execute cmd |" do it
1845
1846With the '|' character the command is separated from the next one. And that
Bram Moolenaar9e1d2832007-05-06 12:51:41 +00001847next command is only a comment. For the last command you need to do two
1848things: |:execute| and use '|': >
1849 :exe '!ls *.c' |" list C files
Bram Moolenaar071d4272004-06-13 20:20:40 +00001850
1851Notice that there is no white space before the '|' in the abbreviation and
1852mapping. For these commands, any character until the end-of-line or '|' is
1853included. As a consequence of this behavior, you don't always see that
1854trailing whitespace is included: >
1855
1856 :map <F4> o#include
1857
Bram Moolenaar9e1d2832007-05-06 12:51:41 +00001858To spot these problems, you can set the 'list' option when editing vimrc
Bram Moolenaar071d4272004-06-13 20:20:40 +00001859files.
1860
Bram Moolenaar9e1d2832007-05-06 12:51:41 +00001861For Unix there is one special way to comment a line, that allows making a Vim
1862script executable: >
1863 #!/usr/bin/env vim -S
1864 echo "this is a Vim script"
1865 quit
1866
1867The "#" command by itself lists a line with the line number. Adding an
1868exclamation mark changes it into doing nothing, so that you can add the shell
1869command to execute the rest of the file. |:#!| |-S|
1870
Bram Moolenaar071d4272004-06-13 20:20:40 +00001871
1872PITFALLS
1873
1874Even bigger problem arises in the following example: >
1875
1876 :map ,ab o#include
1877 :unmap ,ab
1878
1879Here the unmap command will not work, because it tries to unmap ",ab ". This
1880does not exist as a mapped sequence. An error will be issued, which is very
1881hard to identify, because the ending whitespace character in ":unmap ,ab " is
1882not visible.
1883
1884And this is the same as what happens when one uses a comment after an 'unmap'
1885command: >
1886
1887 :unmap ,ab " comment
1888
1889Here the comment part will be ignored. However, Vim will try to unmap
1890',ab ', which does not exist. Rewrite it as: >
1891
1892 :unmap ,ab| " comment
1893
1894
1895RESTORING THE VIEW
1896
Bram Moolenaar3a0d8092012-10-21 03:02:54 +02001897Sometimes you want to make a change and go back to where the cursor was.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001898Restoring the relative position would also be nice, so that the same line
1899appears at the top of the window.
1900 This example yanks the current line, puts it above the first line in the
1901file and then restores the view: >
1902
1903 map ,p ma"aYHmbgg"aP`bzt`a
1904
1905What this does: >
1906 ma"aYHmbgg"aP`bzt`a
1907< ma set mark a at cursor position
1908 "aY yank current line into register a
1909 Hmb go to top line in window and set mark b there
1910 gg go to first line in file
1911 "aP put the yanked line above it
1912 `b go back to top line in display
1913 zt position the text in the window as before
1914 `a go back to saved cursor position
1915
1916
1917PACKAGING
1918
1919To avoid your function names to interfere with functions that you get from
1920others, use this scheme:
1921- Prepend a unique string before each function name. I often use an
1922 abbreviation. For example, "OW_" is used for the option window functions.
1923- Put the definition of your functions together in a file. Set a global
1924 variable to indicate that the functions have been loaded. When sourcing the
1925 file again, first unload the functions.
1926Example: >
1927
1928 " This is the XXX package
1929
1930 if exists("XXX_loaded")
1931 delfun XXX_one
1932 delfun XXX_two
1933 endif
1934
1935 function XXX_one(a)
1936 ... body of function ...
1937 endfun
1938
1939 function XXX_two(b)
1940 ... body of function ...
1941 endfun
1942
1943 let XXX_loaded = 1
1944
1945==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00001946*41.11* Writing a plugin *write-plugin*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001947
1948You can write a Vim script in such a way that many people can use it. This is
1949called a plugin. Vim users can drop your script in their plugin directory and
1950use its features right away |add-plugin|.
1951
1952There are actually two types of plugins:
1953
1954 global plugins: For all types of files.
1955filetype plugins: Only for files of a specific type.
1956
1957In this section the first type is explained. Most items are also relevant for
1958writing filetype plugins. The specifics for filetype plugins are in the next
1959section |write-filetype-plugin|.
1960
1961
1962NAME
1963
1964First of all you must choose a name for your plugin. The features provided
1965by the plugin should be clear from its name. And it should be unlikely that
1966someone else writes a plugin with the same name but which does something
1967different. And please limit the name to 8 characters, to avoid problems on
Bram Moolenaar6f345a12019-12-17 21:27:18 +01001968old MS-Windows systems.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001969
1970A script that corrects typing mistakes could be called "typecorr.vim". We
1971will use it here as an example.
1972
1973For the plugin to work for everybody, it should follow a few guidelines. This
1974will be explained step-by-step. The complete example plugin is at the end.
1975
1976
1977BODY
1978
1979Let's start with the body of the plugin, the lines that do the actual work: >
1980
1981 14 iabbrev teh the
1982 15 iabbrev otehr other
1983 16 iabbrev wnat want
1984 17 iabbrev synchronisation
1985 18 \ synchronization
1986 19 let s:count = 4
1987
1988The actual list should be much longer, of course.
1989
1990The line numbers have only been added to explain a few things, don't put them
1991in your plugin file!
1992
1993
1994HEADER
1995
1996You will probably add new corrections to the plugin and soon have several
Bram Moolenaard09acef2012-09-21 14:54:30 +02001997versions lying around. And when distributing this file, people will want to
Bram Moolenaar071d4272004-06-13 20:20:40 +00001998know who wrote this wonderful plugin and where they can send remarks.
1999Therefore, put a header at the top of your plugin: >
2000
2001 1 " Vim global plugin for correcting typing mistakes
2002 2 " Last Change: 2000 Oct 15
2003 3 " Maintainer: Bram Moolenaar <Bram@vim.org>
2004
2005About copyright and licensing: Since plugins are very useful and it's hardly
2006worth restricting their distribution, please consider making your plugin
2007either public domain or use the Vim |license|. A short note about this near
2008the top of the plugin should be sufficient. Example: >
2009
2010 4 " License: This file is placed in the public domain.
2011
2012
2013LINE CONTINUATION, AVOIDING SIDE EFFECTS *use-cpo-save*
2014
2015In line 18 above, the line-continuation mechanism is used |line-continuation|.
2016Users with 'compatible' set will run into trouble here, they will get an error
2017message. We can't just reset 'compatible', because that has a lot of side
2018effects. To avoid this, we will set the 'cpoptions' option to its Vim default
2019value and restore it later. That will allow the use of line-continuation and
2020make the script work for most people. It is done like this: >
2021
2022 11 let s:save_cpo = &cpo
2023 12 set cpo&vim
2024 ..
2025 42 let &cpo = s:save_cpo
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02002026 43 unlet s:save_cpo
Bram Moolenaar071d4272004-06-13 20:20:40 +00002027
2028We first store the old value of 'cpoptions' in the s:save_cpo variable. At
2029the end of the plugin this value is restored.
2030
2031Notice that a script-local variable is used |s:var|. A global variable could
2032already be in use for something else. Always use script-local variables for
2033things that are only used in the script.
2034
2035
2036NOT LOADING
2037
2038It's possible that a user doesn't always want to load this plugin. Or the
2039system administrator has dropped it in the system-wide plugin directory, but a
2040user has his own plugin he wants to use. Then the user must have a chance to
2041disable loading this specific plugin. This will make it possible: >
2042
Bram Moolenaarc5604bc2010-07-17 15:20:30 +02002043 6 if exists("g:loaded_typecorr")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002044 7 finish
2045 8 endif
Bram Moolenaarc5604bc2010-07-17 15:20:30 +02002046 9 let g:loaded_typecorr = 1
Bram Moolenaar071d4272004-06-13 20:20:40 +00002047
2048This also avoids that when the script is loaded twice it would cause error
2049messages for redefining functions and cause trouble for autocommands that are
2050added twice.
2051
Bram Moolenaarc5604bc2010-07-17 15:20:30 +02002052The name is recommended to start with "loaded_" and then the file name of the
2053plugin, literally. The "g:" is prepended just to avoid mistakes when using
2054the variable in a function (without "g:" it would be a variable local to the
2055function).
2056
2057Using "finish" stops Vim from reading the rest of the file, it's much quicker
2058than using if-endif around the whole file.
2059
Bram Moolenaar071d4272004-06-13 20:20:40 +00002060
2061MAPPING
2062
2063Now let's make the plugin more interesting: We will add a mapping that adds a
2064correction for the word under the cursor. We could just pick a key sequence
2065for this mapping, but the user might already use it for something else. To
2066allow the user to define which keys a mapping in a plugin uses, the <Leader>
2067item can be used: >
2068
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02002069 22 map <unique> <Leader>a <Plug>TypecorrAdd;
Bram Moolenaar071d4272004-06-13 20:20:40 +00002070
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02002071The "<Plug>TypecorrAdd;" thing will do the work, more about that further on.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002072
2073The user can set the "mapleader" variable to the key sequence that he wants
2074this mapping to start with. Thus if the user has done: >
2075
2076 let mapleader = "_"
2077
2078the mapping will define "_a". If the user didn't do this, the default value
2079will be used, which is a backslash. Then a map for "\a" will be defined.
2080
2081Note that <unique> is used, this will cause an error message if the mapping
2082already happened to exist. |:map-<unique>|
2083
2084But what if the user wants to define his own key sequence? We can allow that
2085with this mechanism: >
2086
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02002087 21 if !hasmapto('<Plug>TypecorrAdd;')
2088 22 map <unique> <Leader>a <Plug>TypecorrAdd;
Bram Moolenaar071d4272004-06-13 20:20:40 +00002089 23 endif
2090
Bram Moolenaar207f0092020-08-30 17:20:20 +02002091This checks if a mapping to "<Plug>TypecorrAdd;" already exists, and only
Bram Moolenaar071d4272004-06-13 20:20:40 +00002092defines the mapping from "<Leader>a" if it doesn't. The user then has a
2093chance of putting this in his vimrc file: >
2094
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02002095 map ,c <Plug>TypecorrAdd;
Bram Moolenaar071d4272004-06-13 20:20:40 +00002096
2097Then the mapped key sequence will be ",c" instead of "_a" or "\a".
2098
2099
2100PIECES
2101
2102If a script gets longer, you often want to break up the work in pieces. You
2103can use functions or mappings for this. But you don't want these functions
2104and mappings to interfere with the ones from other scripts. For example, you
2105could define a function Add(), but another script could try to define the same
2106function. To avoid this, we define the function local to the script by
2107prepending it with "s:".
2108
2109We will define a function that adds a new typing correction: >
2110
2111 30 function s:Add(from, correct)
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02002112 31 let to = input("type the correction for " .. a:from .. ": ")
2113 32 exe ":iabbrev " .. a:from .. " " .. to
Bram Moolenaar071d4272004-06-13 20:20:40 +00002114 ..
2115 36 endfunction
2116
2117Now we can call the function s:Add() from within this script. If another
2118script also defines s:Add(), it will be local to that script and can only
2119be called from the script it was defined in. There can also be a global Add()
2120function (without the "s:"), which is again another function.
2121
2122<SID> can be used with mappings. It generates a script ID, which identifies
2123the current script. In our typing correction plugin we use it like this: >
2124
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02002125 24 noremap <unique> <script> <Plug>TypecorrAdd; <SID>Add
Bram Moolenaar071d4272004-06-13 20:20:40 +00002126 ..
2127 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), 1)<CR>
2128
2129Thus when a user types "\a", this sequence is invoked: >
2130
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02002131 \a -> <Plug>TypecorrAdd; -> <SID>Add -> :call <SID>Add()
Bram Moolenaar071d4272004-06-13 20:20:40 +00002132
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02002133If another script also maps <SID>Add, it will get another script ID and
Bram Moolenaar071d4272004-06-13 20:20:40 +00002134thus define another mapping.
2135
2136Note that instead of s:Add() we use <SID>Add() here. That is because the
2137mapping is typed by the user, thus outside of the script. The <SID> is
2138translated to the script ID, so that Vim knows in which script to look for
2139the Add() function.
2140
2141This is a bit complicated, but it's required for the plugin to work together
2142with other plugins. The basic rule is that you use <SID>Add() in mappings and
2143s:Add() in other places (the script itself, autocommands, user commands).
2144
2145We can also add a menu entry to do the same as the mapping: >
2146
2147 26 noremenu <script> Plugin.Add\ Correction <SID>Add
2148
2149The "Plugin" menu is recommended for adding menu items for plugins. In this
2150case only one item is used. When adding more items, creating a submenu is
2151recommended. For example, "Plugin.CVS" could be used for a plugin that offers
2152CVS operations "Plugin.CVS.checkin", "Plugin.CVS.checkout", etc.
2153
2154Note that in line 28 ":noremap" is used to avoid that any other mappings cause
2155trouble. Someone may have remapped ":call", for example. In line 24 we also
2156use ":noremap", but we do want "<SID>Add" to be remapped. This is why
2157"<script>" is used here. This only allows mappings which are local to the
2158script. |:map-<script>| The same is done in line 26 for ":noremenu".
2159|:menu-<script>|
2160
2161
2162<SID> AND <Plug> *using-<Plug>*
2163
2164Both <SID> and <Plug> are used to avoid that mappings of typed keys interfere
2165with mappings that are only to be used from other mappings. Note the
2166difference between using <SID> and <Plug>:
2167
2168<Plug> is visible outside of the script. It is used for mappings which the
2169 user might want to map a key sequence to. <Plug> is a special code
2170 that a typed key will never produce.
2171 To make it very unlikely that other plugins use the same sequence of
2172 characters, use this structure: <Plug> scriptname mapname
2173 In our example the scriptname is "Typecorr" and the mapname is "Add".
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02002174 We add a semicolon as the terminator. This results in
2175 "<Plug>TypecorrAdd;". Only the first character of scriptname and
2176 mapname is uppercase, so that we can see where mapname starts.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002177
2178<SID> is the script ID, a unique identifier for a script.
2179 Internally Vim translates <SID> to "<SNR>123_", where "123" can be any
2180 number. Thus a function "<SID>Add()" will have a name "<SNR>11_Add()"
2181 in one script, and "<SNR>22_Add()" in another. You can see this if
2182 you use the ":function" command to get a list of functions. The
2183 translation of <SID> in mappings is exactly the same, that's how you
2184 can call a script-local function from a mapping.
2185
2186
2187USER COMMAND
2188
2189Now let's add a user command to add a correction: >
2190
2191 38 if !exists(":Correct")
2192 39 command -nargs=1 Correct :call s:Add(<q-args>, 0)
2193 40 endif
2194
2195The user command is defined only if no command with the same name already
2196exists. Otherwise we would get an error here. Overriding the existing user
2197command with ":command!" is not a good idea, this would probably make the user
2198wonder why the command he defined himself doesn't work. |:command|
2199
2200
2201SCRIPT VARIABLES
2202
2203When a variable starts with "s:" it is a script variable. It can only be used
2204inside a script. Outside the script it's not visible. This avoids trouble
2205with using the same variable name in different scripts. The variables will be
2206kept as long as Vim is running. And the same variables are used when sourcing
2207the same script again. |s:var|
2208
2209The fun is that these variables can also be used in functions, autocommands
2210and user commands that are defined in the script. In our example we can add
2211a few lines to count the number of corrections: >
2212
2213 19 let s:count = 4
2214 ..
2215 30 function s:Add(from, correct)
2216 ..
2217 34 let s:count = s:count + 1
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02002218 35 echo s:count .. " corrections now"
Bram Moolenaar071d4272004-06-13 20:20:40 +00002219 36 endfunction
2220
2221First s:count is initialized to 4 in the script itself. When later the
2222s:Add() function is called, it increments s:count. It doesn't matter from
2223where the function was called, since it has been defined in the script, it
2224will use the local variables from this script.
2225
2226
2227THE RESULT
2228
2229Here is the resulting complete example: >
2230
2231 1 " Vim global plugin for correcting typing mistakes
2232 2 " Last Change: 2000 Oct 15
2233 3 " Maintainer: Bram Moolenaar <Bram@vim.org>
2234 4 " License: This file is placed in the public domain.
2235 5
Bram Moolenaarc5604bc2010-07-17 15:20:30 +02002236 6 if exists("g:loaded_typecorr")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002237 7 finish
2238 8 endif
Bram Moolenaarc5604bc2010-07-17 15:20:30 +02002239 9 let g:loaded_typecorr = 1
Bram Moolenaar071d4272004-06-13 20:20:40 +00002240 10
2241 11 let s:save_cpo = &cpo
2242 12 set cpo&vim
2243 13
2244 14 iabbrev teh the
2245 15 iabbrev otehr other
2246 16 iabbrev wnat want
2247 17 iabbrev synchronisation
2248 18 \ synchronization
2249 19 let s:count = 4
2250 20
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02002251 21 if !hasmapto('<Plug>TypecorrAdd;')
2252 22 map <unique> <Leader>a <Plug>TypecorrAdd;
Bram Moolenaar071d4272004-06-13 20:20:40 +00002253 23 endif
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02002254 24 noremap <unique> <script> <Plug>TypecorrAdd; <SID>Add
Bram Moolenaar071d4272004-06-13 20:20:40 +00002255 25
2256 26 noremenu <script> Plugin.Add\ Correction <SID>Add
2257 27
2258 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), 1)<CR>
2259 29
2260 30 function s:Add(from, correct)
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02002261 31 let to = input("type the correction for " .. a:from .. ": ")
2262 32 exe ":iabbrev " .. a:from .. " " .. to
Bram Moolenaar071d4272004-06-13 20:20:40 +00002263 33 if a:correct | exe "normal viws\<C-R>\" \b\e" | endif
2264 34 let s:count = s:count + 1
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02002265 35 echo s:count .. " corrections now"
Bram Moolenaar071d4272004-06-13 20:20:40 +00002266 36 endfunction
2267 37
2268 38 if !exists(":Correct")
2269 39 command -nargs=1 Correct :call s:Add(<q-args>, 0)
2270 40 endif
2271 41
2272 42 let &cpo = s:save_cpo
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02002273 43 unlet s:save_cpo
Bram Moolenaar071d4272004-06-13 20:20:40 +00002274
2275Line 33 wasn't explained yet. It applies the new correction to the word under
2276the cursor. The |:normal| command is used to use the new abbreviation. Note
2277that mappings and abbreviations are expanded here, even though the function
2278was called from a mapping defined with ":noremap".
2279
2280Using "unix" for the 'fileformat' option is recommended. The Vim scripts will
2281then work everywhere. Scripts with 'fileformat' set to "dos" do not work on
2282Unix. Also see |:source_crnl|. To be sure it is set right, do this before
2283writing the file: >
2284
2285 :set fileformat=unix
2286
2287
2288DOCUMENTATION *write-local-help*
2289
2290It's a good idea to also write some documentation for your plugin. Especially
2291when its behavior can be changed by the user. See |add-local-help| for how
2292they are installed.
2293
2294Here is a simple example for a plugin help file, called "typecorr.txt": >
2295
2296 1 *typecorr.txt* Plugin for correcting typing mistakes
2297 2
2298 3 If you make typing mistakes, this plugin will have them corrected
2299 4 automatically.
2300 5
2301 6 There are currently only a few corrections. Add your own if you like.
2302 7
2303 8 Mappings:
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02002304 9 <Leader>a or <Plug>TypecorrAdd;
Bram Moolenaar071d4272004-06-13 20:20:40 +00002305 10 Add a correction for the word under the cursor.
2306 11
2307 12 Commands:
2308 13 :Correct {word}
2309 14 Add a correction for {word}.
2310 15
2311 16 *typecorr-settings*
2312 17 This plugin doesn't have any settings.
2313
2314The first line is actually the only one for which the format matters. It will
2315be extracted from the help file to be put in the "LOCAL ADDITIONS:" section of
2316help.txt |local-additions|. The first "*" must be in the first column of the
2317first line. After adding your help file do ":help" and check that the entries
2318line up nicely.
2319
2320You can add more tags inside ** in your help file. But be careful not to use
2321existing help tags. You would probably use the name of your plugin in most of
2322them, like "typecorr-settings" in the example.
2323
2324Using references to other parts of the help in || is recommended. This makes
2325it easy for the user to find associated help.
2326
2327
2328FILETYPE DETECTION *plugin-filetype*
2329
2330If your filetype is not already detected by Vim, you should create a filetype
2331detection snippet in a separate file. It is usually in the form of an
2332autocommand that sets the filetype when the file name matches a pattern.
2333Example: >
2334
2335 au BufNewFile,BufRead *.foo set filetype=foofoo
2336
2337Write this single-line file as "ftdetect/foofoo.vim" in the first directory
2338that appears in 'runtimepath'. For Unix that would be
2339"~/.vim/ftdetect/foofoo.vim". The convention is to use the name of the
2340filetype for the script name.
2341
2342You can make more complicated checks if you like, for example to inspect the
2343contents of the file to recognize the language. Also see |new-filetype|.
2344
2345
2346SUMMARY *plugin-special*
2347
2348Summary of special things to use in a plugin:
2349
2350s:name Variables local to the script.
2351
2352<SID> Script-ID, used for mappings and functions local to
2353 the script.
2354
2355hasmapto() Function to test if the user already defined a mapping
2356 for functionality the script offers.
2357
2358<Leader> Value of "mapleader", which the user defines as the
2359 keys that plugin mappings start with.
2360
2361:map <unique> Give a warning if a mapping already exists.
2362
2363:noremap <script> Use only mappings local to the script, not global
2364 mappings.
2365
2366exists(":Cmd") Check if a user command already exists.
2367
2368==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00002369*41.12* Writing a filetype plugin *write-filetype-plugin* *ftplugin*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002370
2371A filetype plugin is like a global plugin, except that it sets options and
2372defines mappings for the current buffer only. See |add-filetype-plugin| for
2373how this type of plugin is used.
2374
Bram Moolenaar7c626922005-02-07 22:01:03 +00002375First read the section on global plugins above |41.11|. All that is said there
Bram Moolenaar071d4272004-06-13 20:20:40 +00002376also applies to filetype plugins. There are a few extras, which are explained
2377here. The essential thing is that a filetype plugin should only have an
2378effect on the current buffer.
2379
2380
2381DISABLING
2382
2383If you are writing a filetype plugin to be used by many people, they need a
2384chance to disable loading it. Put this at the top of the plugin: >
2385
2386 " Only do this when not done yet for this buffer
2387 if exists("b:did_ftplugin")
2388 finish
2389 endif
2390 let b:did_ftplugin = 1
2391
2392This also needs to be used to avoid that the same plugin is executed twice for
2393the same buffer (happens when using an ":edit" command without arguments).
2394
2395Now users can disable loading the default plugin completely by making a
2396filetype plugin with only this line: >
2397
2398 let b:did_ftplugin = 1
2399
2400This does require that the filetype plugin directory comes before $VIMRUNTIME
2401in 'runtimepath'!
2402
2403If you do want to use the default plugin, but overrule one of the settings,
2404you can write the different setting in a script: >
2405
2406 setlocal textwidth=70
2407
2408Now write this in the "after" directory, so that it gets sourced after the
2409distributed "vim.vim" ftplugin |after-directory|. For Unix this would be
2410"~/.vim/after/ftplugin/vim.vim". Note that the default plugin will have set
2411"b:did_ftplugin", but it is ignored here.
2412
2413
2414OPTIONS
2415
2416To make sure the filetype plugin only affects the current buffer use the >
2417
2418 :setlocal
2419
2420command to set options. And only set options which are local to a buffer (see
2421the help for the option to check that). When using |:setlocal| for global
2422options or options local to a window, the value will change for many buffers,
2423and that is not what a filetype plugin should do.
2424
2425When an option has a value that is a list of flags or items, consider using
2426"+=" and "-=" to keep the existing value. Be aware that the user may have
2427changed an option value already. First resetting to the default value and
Bram Moolenaard58e9292011-02-09 17:07:58 +01002428then changing it is often a good idea. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002429
2430 :setlocal formatoptions& formatoptions+=ro
2431
2432
2433MAPPINGS
2434
2435To make sure mappings will only work in the current buffer use the >
2436
2437 :map <buffer>
2438
2439command. This needs to be combined with the two-step mapping explained above.
2440An example of how to define functionality in a filetype plugin: >
2441
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02002442 if !hasmapto('<Plug>JavaImport;')
2443 map <buffer> <unique> <LocalLeader>i <Plug>JavaImport;
Bram Moolenaar071d4272004-06-13 20:20:40 +00002444 endif
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02002445 noremap <buffer> <unique> <Plug>JavaImport; oimport ""<Left><Esc>
Bram Moolenaar071d4272004-06-13 20:20:40 +00002446
2447|hasmapto()| is used to check if the user has already defined a map to
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02002448<Plug>JavaImport;. If not, then the filetype plugin defines the default
Bram Moolenaar071d4272004-06-13 20:20:40 +00002449mapping. This starts with |<LocalLeader>|, which allows the user to select
2450the key(s) he wants filetype plugin mappings to start with. The default is a
2451backslash.
2452"<unique>" is used to give an error message if the mapping already exists or
2453overlaps with an existing mapping.
2454|:noremap| is used to avoid that any other mappings that the user has defined
2455interferes. You might want to use ":noremap <script>" to allow remapping
2456mappings defined in this script that start with <SID>.
2457
2458The user must have a chance to disable the mappings in a filetype plugin,
2459without disabling everything. Here is an example of how this is done for a
2460plugin for the mail filetype: >
2461
2462 " Add mappings, unless the user didn't want this.
2463 if !exists("no_plugin_maps") && !exists("no_mail_maps")
2464 " Quote text by inserting "> "
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02002465 if !hasmapto('<Plug>MailQuote;')
2466 vmap <buffer> <LocalLeader>q <Plug>MailQuote;
2467 nmap <buffer> <LocalLeader>q <Plug>MailQuote;
Bram Moolenaar071d4272004-06-13 20:20:40 +00002468 endif
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02002469 vnoremap <buffer> <Plug>MailQuote; :s/^/> /<CR>
2470 nnoremap <buffer> <Plug>MailQuote; :.,$s/^/> /<CR>
Bram Moolenaar071d4272004-06-13 20:20:40 +00002471 endif
2472
2473Two global variables are used:
Bram Moolenaare0720cb2017-03-29 13:48:40 +02002474|no_plugin_maps| disables mappings for all filetype plugins
2475|no_mail_maps| disables mappings for the "mail" filetype
Bram Moolenaar071d4272004-06-13 20:20:40 +00002476
2477
2478USER COMMANDS
2479
2480To add a user command for a specific file type, so that it can only be used in
2481one buffer, use the "-buffer" argument to |:command|. Example: >
2482
2483 :command -buffer Make make %:r.s
2484
2485
2486VARIABLES
2487
2488A filetype plugin will be sourced for each buffer of the type it's for. Local
2489script variables |s:var| will be shared between all invocations. Use local
2490buffer variables |b:var| if you want a variable specifically for one buffer.
2491
2492
2493FUNCTIONS
2494
2495When defining a function, this only needs to be done once. But the filetype
2496plugin will be sourced every time a file with this filetype will be opened.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02002497This construct makes sure the function is only defined once: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002498
2499 :if !exists("*s:Func")
2500 : function s:Func(arg)
2501 : ...
2502 : endfunction
2503 :endif
2504<
2505
Bram Moolenaar38a55632016-02-15 22:07:32 +01002506UNDO *undo_indent* *undo_ftplugin*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002507
2508When the user does ":setfiletype xyz" the effect of the previous filetype
2509should be undone. Set the b:undo_ftplugin variable to the commands that will
2510undo the settings in your filetype plugin. Example: >
2511
2512 let b:undo_ftplugin = "setlocal fo< com< tw< commentstring<"
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02002513 \ .. "| unlet b:match_ignorecase b:match_words b:match_skip"
Bram Moolenaar071d4272004-06-13 20:20:40 +00002514
2515Using ":setlocal" with "<" after the option name resets the option to its
2516global value. That is mostly the best way to reset the option value.
2517
2518This does require removing the "C" flag from 'cpoptions' to allow line
2519continuation, as mentioned above |use-cpo-save|.
2520
Bram Moolenaar38a55632016-02-15 22:07:32 +01002521For undoing the effect of an indent script, the b:undo_indent variable should
2522be set accordingly.
2523
Bram Moolenaar071d4272004-06-13 20:20:40 +00002524
2525FILE NAME
2526
2527The filetype must be included in the file name |ftplugin-name|. Use one of
2528these three forms:
2529
2530 .../ftplugin/stuff.vim
2531 .../ftplugin/stuff_foo.vim
2532 .../ftplugin/stuff/bar.vim
2533
2534"stuff" is the filetype, "foo" and "bar" are arbitrary names.
2535
2536
2537SUMMARY *ftplugin-special*
2538
2539Summary of special things to use in a filetype plugin:
2540
2541<LocalLeader> Value of "maplocalleader", which the user defines as
2542 the keys that filetype plugin mappings start with.
2543
2544:map <buffer> Define a mapping local to the buffer.
2545
2546:noremap <script> Only remap mappings defined in this script that start
2547 with <SID>.
2548
2549:setlocal Set an option for the current buffer only.
2550
2551:command -buffer Define a user command local to the buffer.
2552
2553exists("*s:Func") Check if a function was already defined.
2554
2555Also see |plugin-special|, the special things used for all plugins.
2556
2557==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00002558*41.13* Writing a compiler plugin *write-compiler-plugin*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002559
2560A compiler plugin sets options for use with a specific compiler. The user can
2561load it with the |:compiler| command. The main use is to set the
2562'errorformat' and 'makeprg' options.
2563
2564Easiest is to have a look at examples. This command will edit all the default
2565compiler plugins: >
2566
2567 :next $VIMRUNTIME/compiler/*.vim
2568
2569Use |:next| to go to the next plugin file.
2570
2571There are two special items about these files. First is a mechanism to allow
2572a user to overrule or add to the default file. The default files start with: >
2573
2574 :if exists("current_compiler")
2575 : finish
2576 :endif
2577 :let current_compiler = "mine"
2578
2579When you write a compiler file and put it in your personal runtime directory
2580(e.g., ~/.vim/compiler for Unix), you set the "current_compiler" variable to
2581make the default file skip the settings.
Bram Moolenaarc6039d82005-12-02 00:44:04 +00002582 *:CompilerSet*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002583The second mechanism is to use ":set" for ":compiler!" and ":setlocal" for
2584":compiler". Vim defines the ":CompilerSet" user command for this. However,
2585older Vim versions don't, thus your plugin should define it then. This is an
2586example: >
2587
2588 if exists(":CompilerSet") != 2
2589 command -nargs=* CompilerSet setlocal <args>
2590 endif
2591 CompilerSet errorformat& " use the default 'errorformat'
2592 CompilerSet makeprg=nmake
2593
2594When you write a compiler plugin for the Vim distribution or for a system-wide
2595runtime directory, use the mechanism mentioned above. When
2596"current_compiler" was already set by a user plugin nothing will be done.
2597
2598When you write a compiler plugin to overrule settings from a default plugin,
2599don't check "current_compiler". This plugin is supposed to be loaded
2600last, thus it should be in a directory at the end of 'runtimepath'. For Unix
2601that could be ~/.vim/after/compiler.
2602
2603==============================================================================
Bram Moolenaar05159a02005-02-26 23:04:13 +00002604*41.14* Writing a plugin that loads quickly *write-plugin-quickload*
2605
2606A plugin may grow and become quite long. The startup delay may become
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00002607noticeable, while you hardly ever use the plugin. Then it's time for a
Bram Moolenaar05159a02005-02-26 23:04:13 +00002608quickload plugin.
2609
2610The basic idea is that the plugin is loaded twice. The first time user
2611commands and mappings are defined that offer the functionality. The second
2612time the functions that implement the functionality are defined.
2613
2614It may sound surprising that quickload means loading a script twice. What we
2615mean is that it loads quickly the first time, postponing the bulk of the
2616script to the second time, which only happens when you actually use it. When
2617you always use the functionality it actually gets slower!
2618
Bram Moolenaar76916e62006-03-21 21:23:25 +00002619Note that since Vim 7 there is an alternative: use the |autoload|
2620functionality |41.15|.
2621
Bram Moolenaar05159a02005-02-26 23:04:13 +00002622The following example shows how it's done: >
2623
2624 " Vim global plugin for demonstrating quick loading
2625 " Last Change: 2005 Feb 25
2626 " Maintainer: Bram Moolenaar <Bram@vim.org>
2627 " License: This file is placed in the public domain.
2628
2629 if !exists("s:did_load")
2630 command -nargs=* BNRead call BufNetRead(<f-args>)
2631 map <F19> :call BufNetWrite('something')<CR>
2632
2633 let s:did_load = 1
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02002634 exe 'au FuncUndefined BufNet* source ' .. expand('<sfile>')
Bram Moolenaar05159a02005-02-26 23:04:13 +00002635 finish
2636 endif
2637
2638 function BufNetRead(...)
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02002639 echo 'BufNetRead(' .. string(a:000) .. ')'
Bram Moolenaar05159a02005-02-26 23:04:13 +00002640 " read functionality here
2641 endfunction
2642
2643 function BufNetWrite(...)
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02002644 echo 'BufNetWrite(' .. string(a:000) .. ')'
Bram Moolenaar05159a02005-02-26 23:04:13 +00002645 " write functionality here
2646 endfunction
2647
2648When the script is first loaded "s:did_load" is not set. The commands between
2649the "if" and "endif" will be executed. This ends in a |:finish| command, thus
2650the rest of the script is not executed.
2651
2652The second time the script is loaded "s:did_load" exists and the commands
2653after the "endif" are executed. This defines the (possible long)
2654BufNetRead() and BufNetWrite() functions.
2655
2656If you drop this script in your plugin directory Vim will execute it on
2657startup. This is the sequence of events that happens:
2658
26591. The "BNRead" command is defined and the <F19> key is mapped when the script
2660 is sourced at startup. A |FuncUndefined| autocommand is defined. The
2661 ":finish" command causes the script to terminate early.
2662
26632. The user types the BNRead command or presses the <F19> key. The
2664 BufNetRead() or BufNetWrite() function will be called.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00002665
Bram Moolenaar05159a02005-02-26 23:04:13 +000026663. Vim can't find the function and triggers the |FuncUndefined| autocommand
2667 event. Since the pattern "BufNet*" matches the invoked function, the
2668 command "source fname" will be executed. "fname" will be equal to the name
2669 of the script, no matter where it is located, because it comes from
2670 expanding "<sfile>" (see |expand()|).
2671
26724. The script is sourced again, the "s:did_load" variable exists and the
2673 functions are defined.
2674
2675Notice that the functions that are loaded afterwards match the pattern in the
2676|FuncUndefined| autocommand. You must make sure that no other plugin defines
2677functions that match this pattern.
2678
2679==============================================================================
2680*41.15* Writing library scripts *write-library-script*
2681
2682Some functionality will be required in several places. When this becomes more
2683than a few lines you will want to put it in one script and use it from many
2684scripts. We will call that one script a library script.
2685
2686Manually loading a library script is possible, so long as you avoid loading it
2687when it's already done. You can do this with the |exists()| function.
2688Example: >
2689
2690 if !exists('*MyLibFunction')
2691 runtime library/mylibscript.vim
2692 endif
2693 call MyLibFunction(arg)
2694
2695Here you need to know that MyLibFunction() is defined in a script
2696"library/mylibscript.vim" in one of the directories in 'runtimepath'.
2697
2698To make this a bit simpler Vim offers the autoload mechanism. Then the
2699example looks like this: >
2700
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002701 call mylib#myfunction(arg)
Bram Moolenaar05159a02005-02-26 23:04:13 +00002702
2703That's a lot simpler, isn't it? Vim will recognize the function name and when
2704it's not defined search for the script "autoload/mylib.vim" in 'runtimepath'.
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002705That script must define the "mylib#myfunction()" function.
Bram Moolenaar05159a02005-02-26 23:04:13 +00002706
2707You can put many other functions in the mylib.vim script, you are free to
2708organize your functions in library scripts. But you must use function names
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00002709where the part before the '#' matches the script name. Otherwise Vim would
2710not know what script to load.
Bram Moolenaar05159a02005-02-26 23:04:13 +00002711
Bram Moolenaard1f56e62006-02-22 21:25:37 +00002712If you get really enthusiastic and write lots of library scripts, you may
Bram Moolenaar05159a02005-02-26 23:04:13 +00002713want to use subdirectories. Example: >
2714
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002715 call netlib#ftp#read('somefile')
Bram Moolenaar05159a02005-02-26 23:04:13 +00002716
2717For Unix the library script used for this could be:
2718
2719 ~/.vim/autoload/netlib/ftp.vim
2720
2721Where the function is defined like this: >
2722
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002723 function netlib#ftp#read(fname)
Bram Moolenaar05159a02005-02-26 23:04:13 +00002724 " Read the file fname through ftp
2725 endfunction
2726
2727Notice that the name the function is defined with is exactly the same as the
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00002728name used for calling the function. And the part before the last '#'
Bram Moolenaar05159a02005-02-26 23:04:13 +00002729exactly matches the subdirectory and script name.
2730
2731You can use the same mechanism for variables: >
2732
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002733 let weekdays = dutch#weekdays
Bram Moolenaar05159a02005-02-26 23:04:13 +00002734
2735This will load the script "autoload/dutch.vim", which should contain something
2736like: >
2737
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002738 let dutch#weekdays = ['zondag', 'maandag', 'dinsdag', 'woensdag',
Bram Moolenaar05159a02005-02-26 23:04:13 +00002739 \ 'donderdag', 'vrijdag', 'zaterdag']
2740
2741Further reading: |autoload|.
2742
2743==============================================================================
Bram Moolenaar76916e62006-03-21 21:23:25 +00002744*41.16* Distributing Vim scripts *distribute-script*
2745
2746Vim users will look for scripts on the Vim website: http://www.vim.org.
2747If you made something that is useful for others, share it!
2748
2749Vim scripts can be used on any system. There might not be a tar or gzip
2750command. If you want to pack files together and/or compress them the "zip"
2751utility is recommended.
2752
2753For utmost portability use Vim itself to pack scripts together. This can be
2754done with the Vimball utility. See |vimball|.
2755
Bram Moolenaarc01140a2006-03-24 22:21:52 +00002756It's good if you add a line to allow automatic updating. See |glvs-plugins|.
2757
Bram Moolenaar76916e62006-03-21 21:23:25 +00002758==============================================================================
Bram Moolenaar071d4272004-06-13 20:20:40 +00002759
2760Next chapter: |usr_42.txt| Add new menus
2761
Bram Moolenaard473c8c2018-08-11 18:00:22 +02002762Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: