blob: 0219b98868196da91860bfc996332645661c4a28 [file] [log] [blame]
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001*usr_41.txt* For Vim version 8.2. Last change: 2020 Jun 01
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 Moolenaarebacddb2020-06-04 15:22:21 +020044Note: if you are familiar with Python, you can find a comparison between
45Python and Vim script here, with pointers to other documents:
46 https://gist.github.com/yegappan/16d964a37ead0979b05e655aa036cad0
47
48
Bram Moolenaar071d4272004-06-13 20:20:40 +000049Let's start with a simple example: >
50
51 :let i = 1
52 :while i < 5
53 : echo "count is" i
Bram Moolenaar7c626922005-02-07 22:01:03 +000054 : let i += 1
Bram Moolenaar071d4272004-06-13 20:20:40 +000055 :endwhile
56<
57 Note:
58 The ":" characters are not really needed here. You only need to use
59 them when you type a command. In a Vim script file they can be left
60 out. We will use them here anyway to make clear these are colon
61 commands and make them stand out from Normal mode commands.
Bram Moolenaar7c626922005-02-07 22:01:03 +000062 Note:
63 You can try out the examples by yanking the lines from the text here
64 and executing them with :@"
Bram Moolenaar071d4272004-06-13 20:20:40 +000065
Bram Moolenaar7c626922005-02-07 22:01:03 +000066The output of the example code is:
67
68 count is 1 ~
69 count is 2 ~
70 count is 3 ~
71 count is 4 ~
72
73In the first line the ":let" command assigns a value to a variable. The
74generic form is: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000075
76 :let {variable} = {expression}
77
78In this case the variable name is "i" and the expression is a simple value,
79the number one.
80 The ":while" command starts a loop. The generic form is: >
81
82 :while {condition}
83 : {statements}
84 :endwhile
85
86The statements until the matching ":endwhile" are executed for as long as the
87condition is true. The condition used here is the expression "i < 5". This
88is true when the variable i is smaller than five.
Bram Moolenaar071d4272004-06-13 20:20:40 +000089 Note:
90 If you happen to write a while loop that keeps on running, you can
91 interrupt it by pressing CTRL-C (CTRL-Break on MS-Windows).
92
Bram Moolenaar7c626922005-02-07 22:01:03 +000093The ":echo" command prints its arguments. In this case the string "count is"
94and the value of the variable i. Since i is one, this will print:
95
96 count is 1 ~
97
98Then there is the ":let i += 1" command. This does the same thing as
99":let i = i + 1". This adds one to the variable i and assigns the new value
100to the same variable.
101
102The example was given to explain the commands, but would you really want to
Bram Moolenaar214641f2017-03-05 17:04:09 +0100103make such a loop, it can be written much more compact: >
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000104
105 :for i in range(1, 4)
106 : echo "count is" i
107 :endfor
108
Bram Moolenaar7c626922005-02-07 22:01:03 +0000109We won't explain how |:for| and |range()| work until later. Follow the links
110if you are impatient.
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000111
Bram Moolenaar071d4272004-06-13 20:20:40 +0000112
Bram Moolenaar7dd64a32019-05-31 21:41:05 +0200113FOUR KINDS OF NUMBERS
Bram Moolenaar071d4272004-06-13 20:20:40 +0000114
Bram Moolenaar7dd64a32019-05-31 21:41:05 +0200115Numbers can be decimal, hexadecimal, octal or binary. A hexadecimal number
116starts with "0x" or "0X". For example "0x1f" is decimal 31. An octal number
117starts with a zero. "017" is decimal 15. A binary number starts with "0b" or
118"0B". For example "0b101" is decimal 5. Careful: don't put a zero before a
119decimal number, it will be interpreted as an octal number!
Bram Moolenaar071d4272004-06-13 20:20:40 +0000120 The ":echo" command always prints decimal numbers. Example: >
121
122 :echo 0x7f 036
123< 127 30 ~
124
Bram Moolenaar7dd64a32019-05-31 21:41:05 +0200125A number is made negative with a minus sign. This also works for hexadecimal,
126octal and binary numbers. A minus sign is also used for subtraction. Compare
127this with the previous example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000128
129 :echo 0x7f -036
130< 97 ~
131
132White space in an expression is ignored. However, it's recommended to use it
133for separating items, to make the expression easier to read. For example, to
Bram Moolenaar7c626922005-02-07 22:01:03 +0000134avoid the confusion with a negative number above, put a space between the
135minus sign and the following number: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000136
137 :echo 0x7f - 036
138
139==============================================================================
140*41.2* Variables
141
142A variable name consists of ASCII letters, digits and the underscore. It
143cannot start with a digit. Valid variable names are:
144
145 counter
146 _aap3
147 very_long_variable_name_with_underscores
148 FuncLength
149 LENGTH
150
151Invalid names are "foo+bar" and "6var".
152 These variables are global. To see a list of currently defined variables
153use this command: >
154
155 :let
156
157You can use global variables everywhere. This also means that when the
158variable "count" is used in one script file, it might also be used in another
159file. This leads to confusion at least, and real problems at worst. To avoid
160this, you can use a variable local to a script file by prepending "s:". For
161example, one script contains this code: >
162
163 :let s:count = 1
164 :while s:count < 5
165 : source other.vim
Bram Moolenaar7c626922005-02-07 22:01:03 +0000166 : let s:count += 1
Bram Moolenaar071d4272004-06-13 20:20:40 +0000167 :endwhile
168
169Since "s:count" is local to this script, you can be sure that sourcing the
170"other.vim" script will not change this variable. If "other.vim" also uses an
171"s:count" variable, it will be a different copy, local to that script. More
172about script-local variables here: |script-variable|.
173
174There are more kinds of variables, see |internal-variables|. The most often
175used ones are:
176
177 b:name variable local to a buffer
178 w:name variable local to a window
179 g:name global variable (also in a function)
180 v:name variable predefined by Vim
181
182
183DELETING VARIABLES
184
185Variables take up memory and show up in the output of the ":let" command. To
186delete a variable use the ":unlet" command. Example: >
187
188 :unlet s:count
189
190This deletes the script-local variable "s:count" to free up the memory it
191uses. If you are not sure if the variable exists, and don't want an error
192message when it doesn't, append !: >
193
194 :unlet! s:count
195
196When a script finishes, the local variables used there will not be
197automatically freed. The next time the script executes, it can still use the
198old value. Example: >
199
200 :if !exists("s:call_count")
201 : let s:call_count = 0
202 :endif
203 :let s:call_count = s:call_count + 1
204 :echo "called" s:call_count "times"
205
206The "exists()" function checks if a variable has already been defined. Its
207argument is the name of the variable you want to check. Not the variable
208itself! If you would do this: >
209
210 :if !exists(s:call_count)
211
212Then the value of s:call_count will be used as the name of the variable that
213exists() checks. That's not what you want.
214 The exclamation mark ! negates a value. When the value was true, it
215becomes false. When it was false, it becomes true. You can read it as "not".
216Thus "if !exists()" can be read as "if not exists()".
Bram Moolenaar7c626922005-02-07 22:01:03 +0000217 What Vim calls true is anything that is not zero. Zero is false.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000218 Note:
Bram Moolenaar7c626922005-02-07 22:01:03 +0000219 Vim automatically converts a string to a number when it is looking for
220 a number. When using a string that doesn't start with a digit the
221 resulting number is zero. Thus look out for this: >
222 :if "true"
223< The "true" will be interpreted as a zero, thus as false!
Bram Moolenaar071d4272004-06-13 20:20:40 +0000224
225
226STRING VARIABLES AND CONSTANTS
227
228So far only numbers were used for the variable value. Strings can be used as
Bram Moolenaar7c626922005-02-07 22:01:03 +0000229well. Numbers and strings are the basic types of variables that Vim supports.
230The type is dynamic, it is set each time when assigning a value to the
231variable with ":let". More about types in |41.8|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000232 To assign a string value to a variable, you need to use a string constant.
233There are two types of these. First the string in double quotes: >
234
235 :let name = "peter"
236 :echo name
237< peter ~
238
239If you want to include a double quote inside the string, put a backslash in
240front of it: >
241
242 :let name = "\"peter\""
243 :echo name
244< "peter" ~
245
246To avoid the need for a backslash, you can use a string in single quotes: >
247
248 :let name = '"peter"'
249 :echo name
250< "peter" ~
251
Bram Moolenaar7c626922005-02-07 22:01:03 +0000252Inside a single-quote string all the characters are as they are. Only the
253single quote itself is special: you need to use two to get one. A backslash
254is taken literally, thus you can't use it to change the meaning of the
Bram Moolenaar071d4272004-06-13 20:20:40 +0000255character after it.
256 In double-quote strings it is possible to use special characters. Here are
257a few useful ones:
258
259 \t <Tab>
260 \n <NL>, line break
261 \r <CR>, <Enter>
262 \e <Esc>
263 \b <BS>, backspace
264 \" "
265 \\ \, backslash
266 \<Esc> <Esc>
267 \<C-W> CTRL-W
268
269The last two are just examples. The "\<name>" form can be used to include
270the special key "name".
271 See |expr-quote| for the full list of special items in a string.
272
273==============================================================================
274*41.3* Expressions
275
276Vim has a rich, yet simple way to handle expressions. You can read the
277definition here: |expression-syntax|. Here we will show the most common
278items.
279 The numbers, strings and variables mentioned above are expressions by
280themselves. Thus everywhere an expression is expected, you can use a number,
281string or variable. Other basic items in an expression are:
282
283 $NAME environment variable
284 &name option
285 @r register
286
287Examples: >
288
289 :echo "The value of 'tabstop' is" &ts
290 :echo "Your home directory is" $HOME
291 :if @a > 5
292
293The &name form can be used to save an option value, set it to a new value,
294do something and restore the old value. Example: >
295
296 :let save_ic = &ic
297 :set noic
298 :/The Start/,$delete
299 :let &ic = save_ic
300
301This makes sure the "The Start" pattern is used with the 'ignorecase' option
Bram Moolenaar7c626922005-02-07 22:01:03 +0000302off. Still, it keeps the value that the user had set. (Another way to do
303this would be to add "\C" to the pattern, see |/\C|.)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000304
305
306MATHEMATICS
307
308It becomes more interesting if we combine these basic items. Let's start with
309mathematics on numbers:
310
311 a + b add
312 a - b subtract
313 a * b multiply
314 a / b divide
315 a % b modulo
316
317The usual precedence is used. Example: >
318
319 :echo 10 + 5 * 2
320< 20 ~
321
Bram Moolenaar00654022011-02-25 14:42:19 +0100322Grouping is done with parentheses. No surprises here. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000323
324 :echo (10 + 5) * 2
325< 30 ~
326
327Strings can be concatenated with ".". Example: >
328
329 :echo "foo" . "bar"
330< foobar ~
331
332When the ":echo" command gets multiple arguments, it separates them with a
333space. In the example the argument is a single expression, thus no space is
334inserted.
335
336Borrowed from the C language is the conditional expression:
337
338 a ? b : c
339
340If "a" evaluates to true "b" is used, otherwise "c" is used. Example: >
341
342 :let i = 4
343 :echo i > 5 ? "i is big" : "i is small"
344< i is small ~
345
346The three parts of the constructs are always evaluated first, thus you could
347see it work as:
348
349 (a) ? (b) : (c)
350
351==============================================================================
352*41.4* Conditionals
353
354The ":if" commands executes the following statements, until the matching
355":endif", only when a condition is met. The generic form is:
356
357 :if {condition}
358 {statements}
359 :endif
360
361Only when the expression {condition} evaluates to true (non-zero) will the
362{statements} be executed. These must still be valid commands. If they
363contain garbage, Vim won't be able to find the ":endif".
364 You can also use ":else". The generic form for this is:
365
366 :if {condition}
367 {statements}
368 :else
369 {statements}
370 :endif
371
372The second {statements} is only executed if the first one isn't.
373 Finally, there is ":elseif":
374
375 :if {condition}
376 {statements}
377 :elseif {condition}
378 {statements}
379 :endif
380
381This works just like using ":else" and then "if", but without the need for an
382extra ":endif".
383 A useful example for your vimrc file is checking the 'term' option and
384doing something depending upon its value: >
385
386 :if &term == "xterm"
387 : " Do stuff for xterm
388 :elseif &term == "vt100"
389 : " Do stuff for a vt100 terminal
390 :else
391 : " Do something for other terminals
392 :endif
393
394
395LOGIC OPERATIONS
396
397We already used some of them in the examples. These are the most often used
398ones:
399
400 a == b equal to
401 a != b not equal to
402 a > b greater than
403 a >= b greater than or equal to
404 a < b less than
405 a <= b less than or equal to
406
407The result is one if the condition is met and zero otherwise. An example: >
408
Bram Moolenaar7c626922005-02-07 22:01:03 +0000409 :if v:version >= 700
Bram Moolenaar071d4272004-06-13 20:20:40 +0000410 : echo "congratulations"
411 :else
412 : echo "you are using an old version, upgrade!"
413 :endif
414
415Here "v:version" is a variable defined by Vim, which has the value of the Vim
416version. 600 is for version 6.0. Version 6.1 has the value 601. This is
417very useful to write a script that works with multiple versions of Vim.
418|v:version|
419
420The logic operators work both for numbers and strings. When comparing two
421strings, the mathematical difference is used. This compares byte values,
422which may not be right for some languages.
423 When comparing a string with a number, the string is first converted to a
424number. This is a bit tricky, because when a string doesn't look like a
425number, the number zero is used. Example: >
426
427 :if 0 == "one"
428 : echo "yes"
429 :endif
430
431This will echo "yes", because "one" doesn't look like a number, thus it is
432converted to the number zero.
433
434For strings there are two more items:
435
436 a =~ b matches with
437 a !~ b does not match with
438
439The left item "a" is used as a string. The right item "b" is used as a
440pattern, like what's used for searching. Example: >
441
442 :if str =~ " "
443 : echo "str contains a space"
444 :endif
445 :if str !~ '\.$'
446 : echo "str does not end in a full stop"
447 :endif
448
449Notice the use of a single-quote string for the pattern. This is useful,
Bram Moolenaar7c626922005-02-07 22:01:03 +0000450because backslashes would need to be doubled in a double-quote string and
451patterns tend to contain many backslashes.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000452
453The 'ignorecase' option is used when comparing strings. When you don't want
454that, append "#" to match case and "?" to ignore case. Thus "==?" compares
455two strings to be equal while ignoring case. And "!~#" checks if a pattern
456doesn't match, also checking the case of letters. For the full table see
457|expr-==|.
458
459
460MORE LOOPING
461
462The ":while" command was already mentioned. Two more statements can be used
463in between the ":while" and the ":endwhile":
464
465 :continue Jump back to the start of the while loop; the
466 loop continues.
467 :break Jump forward to the ":endwhile"; the loop is
468 discontinued.
469
470Example: >
471
472 :while counter < 40
473 : call do_something()
474 : if skip_flag
475 : continue
476 : endif
477 : if finished_flag
478 : break
479 : endif
480 : sleep 50m
481 :endwhile
482
483The ":sleep" command makes Vim take a nap. The "50m" specifies fifty
484milliseconds. Another example is ":sleep 4", which sleeps for four seconds.
485
Bram Moolenaar7c626922005-02-07 22:01:03 +0000486Even more looping can be done with the ":for" command, see below in |41.8|.
487
Bram Moolenaar071d4272004-06-13 20:20:40 +0000488==============================================================================
489*41.5* Executing an expression
490
491So far the commands in the script were executed by Vim directly. The
492":execute" command allows executing the result of an expression. This is a
493very powerful way to build commands and execute them.
494 An example is to jump to a tag, which is contained in a variable: >
495
496 :execute "tag " . tag_name
497
498The "." is used to concatenate the string "tag " with the value of variable
499"tag_name". Suppose "tag_name" has the value "get_cmd", then the command that
500will be executed is: >
501
502 :tag get_cmd
503
504The ":execute" command can only execute colon commands. The ":normal" command
505executes Normal mode commands. However, its argument is not an expression but
506the literal command characters. Example: >
507
508 :normal gg=G
509
510This jumps to the first line and formats all lines with the "=" operator.
511 To make ":normal" work with an expression, combine ":execute" with it.
512Example: >
513
514 :execute "normal " . normal_commands
515
516The variable "normal_commands" must contain the Normal mode commands.
517 Make sure that the argument for ":normal" is a complete command. Otherwise
518Vim will run into the end of the argument and abort the command. For example,
519if you start Insert mode, you must leave Insert mode as well. This works: >
520
521 :execute "normal Inew text \<Esc>"
522
523This inserts "new text " in the current line. Notice the use of the special
524key "\<Esc>". This avoids having to enter a real <Esc> character in your
525script.
526
Bram Moolenaar7c626922005-02-07 22:01:03 +0000527If you don't want to execute a string but evaluate it to get its expression
528value, you can use the eval() function: >
529
530 :let optname = "path"
531 :let optval = eval('&' . optname)
532
533A "&" character is prepended to "path", thus the argument to eval() is
534"&path". The result will then be the value of the 'path' option.
535 The same thing can be done with: >
536 :exe 'let optval = &' . optname
537
Bram Moolenaar071d4272004-06-13 20:20:40 +0000538==============================================================================
539*41.6* Using functions
540
541Vim defines many functions and provides a large amount of functionality that
542way. A few examples will be given in this section. You can find the whole
543list here: |functions|.
544
545A function is called with the ":call" command. The parameters are passed in
Bram Moolenaar00654022011-02-25 14:42:19 +0100546between parentheses separated by commas. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000547
548 :call search("Date: ", "W")
549
550This calls the search() function, with arguments "Date: " and "W". The
551search() function uses its first argument as a search pattern and the second
552one as flags. The "W" flag means the search doesn't wrap around the end of
553the file.
554
555A function can be called in an expression. Example: >
556
557 :let line = getline(".")
558 :let repl = substitute(line, '\a', "*", "g")
559 :call setline(".", repl)
560
Bram Moolenaar7c626922005-02-07 22:01:03 +0000561The getline() function obtains a line from the current buffer. Its argument
562is a specification of the line number. In this case "." is used, which means
563the line where the cursor is.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000564 The substitute() function does something similar to the ":substitute"
565command. The first argument is the string on which to perform the
566substitution. The second argument is the pattern, the third the replacement
567string. Finally, the last arguments are the flags.
568 The setline() function sets the line, specified by the first argument, to a
569new string, the second argument. In this example the line under the cursor is
570replaced with the result of the substitute(). Thus the effect of the three
571statements is equal to: >
572
573 :substitute/\a/*/g
574
575Using the functions becomes more interesting when you do more work before and
576after the substitute() call.
577
578
579FUNCTIONS *function-list*
580
581There are many functions. We will mention them here, grouped by what they are
582used for. You can find an alphabetical list here: |functions|. Use CTRL-] on
583the function name to jump to detailed help on it.
584
Bram Moolenaara3f41662010-07-11 19:01:06 +0200585String manipulation: *string-functions*
Bram Moolenaar9d401282019-04-06 13:18:12 +0200586 nr2char() get a character by its number value
587 list2str() get a character string from a list of numbers
588 char2nr() get number value of a character
589 str2list() get list of numbers from a string
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000590 str2nr() convert a string to a Number
591 str2float() convert a string to a Float
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000592 printf() format a string according to % items
Bram Moolenaar071d4272004-06-13 20:20:40 +0000593 escape() escape characters in a string with a '\'
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000594 shellescape() escape a string for use with a shell command
595 fnameescape() escape a file name for use with a Vim command
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000596 tr() translate characters from one set to another
Bram Moolenaar071d4272004-06-13 20:20:40 +0000597 strtrans() translate a string to make it printable
598 tolower() turn a string to lowercase
599 toupper() turn a string to uppercase
600 match() position where a pattern matches in a string
601 matchend() position where a pattern match ends in a string
602 matchstr() match of a pattern in a string
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +0200603 matchstrpos() match and positions of a pattern in a string
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000604 matchlist() like matchstr() and also return submatches
Bram Moolenaar071d4272004-06-13 20:20:40 +0000605 stridx() first index of a short string in a long string
606 strridx() last index of a short string in a long string
Bram Moolenaar8d043172014-01-23 14:24:41 +0100607 strlen() length of a string in bytes
608 strchars() length of a string in characters
609 strwidth() size of string when displayed
610 strdisplaywidth() size of string when displayed, deals with tabs
Bram Moolenaar071d4272004-06-13 20:20:40 +0000611 substitute() substitute a pattern match with a string
Bram Moolenaar251e1912011-06-19 05:09:16 +0200612 submatch() get a specific match in ":s" and substitute()
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200613 strpart() get part of a string using byte index
614 strcharpart() get part of a string using char index
615 strgetchar() get character from a string using char index
Bram Moolenaar071d4272004-06-13 20:20:40 +0000616 expand() expand special keywords
Bram Moolenaar80dad482019-06-09 17:22:31 +0200617 expandcmd() expand a command like done for `:edit`
Bram Moolenaar071d4272004-06-13 20:20:40 +0000618 iconv() convert text from one encoding to another
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000619 byteidx() byte index of a character in a string
Bram Moolenaar8d043172014-01-23 14:24:41 +0100620 byteidxcomp() like byteidx() but count composing characters
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000621 repeat() repeat a string multiple times
622 eval() evaluate a string expression
Bram Moolenaar063b9d12016-07-09 20:21:48 +0200623 execute() execute an Ex command and get the output
Bram Moolenaar7dd64a32019-05-31 21:41:05 +0200624 win_execute() like execute() but in a specified window
Bram Moolenaarb730f0c2018-11-25 03:56:26 +0100625 trim() trim characters from a string
Bram Moolenaar071d4272004-06-13 20:20:40 +0000626
Bram Moolenaara3f41662010-07-11 19:01:06 +0200627List manipulation: *list-functions*
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000628 get() get an item without error for wrong index
629 len() number of items in a List
630 empty() check if List is empty
631 insert() insert an item somewhere in a List
632 add() append an item to a List
633 extend() append a List to a List
634 remove() remove one or more items from a List
635 copy() make a shallow copy of a List
636 deepcopy() make a full copy of a List
637 filter() remove selected items from a List
638 map() change each List item
Bram Moolenaarebacddb2020-06-04 15:22:21 +0200639 reduce() reduce a List to a value
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000640 sort() sort a List
641 reverse() reverse the order of a List
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +0100642 uniq() remove copies of repeated adjacent items
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000643 split() split a String into a List
644 join() join List items into a String
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000645 range() return a List with a sequence of numbers
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000646 string() String representation of a List
647 call() call a function with List as arguments
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000648 index() index of a value in a List
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000649 max() maximum value in a List
650 min() minimum value in a List
651 count() count number of times a value appears in a List
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000652 repeat() repeat a List multiple times
Bram Moolenaar077a1e62020-06-08 20:50:43 +0200653 flatten() flatten a List
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000654
Bram Moolenaara3f41662010-07-11 19:01:06 +0200655Dictionary manipulation: *dict-functions*
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000656 get() get an entry without an error for a wrong key
Bram Moolenaaraf7f6412005-01-17 22:11:23 +0000657 len() number of entries in a Dictionary
658 has_key() check whether a key appears in a Dictionary
659 empty() check if Dictionary is empty
660 remove() remove an entry from a Dictionary
661 extend() add entries from one Dictionary to another
662 filter() remove selected entries from a Dictionary
663 map() change each Dictionary entry
664 keys() get List of Dictionary keys
665 values() get List of Dictionary values
666 items() get List of Dictionary key-value pairs
667 copy() make a shallow copy of a Dictionary
668 deepcopy() make a full copy of a Dictionary
669 string() String representation of a Dictionary
670 max() maximum value in a Dictionary
671 min() minimum value in a Dictionary
672 count() count number of times a value appears
673
Bram Moolenaara3f41662010-07-11 19:01:06 +0200674Floating point computation: *float-functions*
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000675 float2nr() convert Float to Number
676 abs() absolute value (also works for Number)
677 round() round off
678 ceil() round up
679 floor() round down
680 trunc() remove value after decimal point
Bram Moolenaar8d043172014-01-23 14:24:41 +0100681 fmod() remainder of division
682 exp() exponential
683 log() natural logarithm (logarithm to base e)
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000684 log10() logarithm to base 10
685 pow() value of x to the exponent y
686 sqrt() square root
687 sin() sine
688 cos() cosine
Bram Moolenaar662db672011-03-22 14:05:35 +0100689 tan() tangent
690 asin() arc sine
691 acos() arc cosine
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000692 atan() arc tangent
Bram Moolenaar662db672011-03-22 14:05:35 +0100693 atan2() arc tangent
694 sinh() hyperbolic sine
695 cosh() hyperbolic cosine
696 tanh() hyperbolic tangent
Bram Moolenaarebacddb2020-06-04 15:22:21 +0200697 isinf() check for infinity
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200698 isnan() check for not a number
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000699
Bram Moolenaarb6b046b2011-12-30 13:11:27 +0100700Other computation: *bitwise-function*
701 and() bitwise AND
702 invert() bitwise invert
703 or() bitwise OR
704 xor() bitwise XOR
Bram Moolenaar8d043172014-01-23 14:24:41 +0100705 sha256() SHA-256 hash
Bram Moolenaarebacddb2020-06-04 15:22:21 +0200706 rand() get a pseudo-random number
707 srand() initialize seed used by rand()
Bram Moolenaarb6b046b2011-12-30 13:11:27 +0100708
Bram Moolenaara3f41662010-07-11 19:01:06 +0200709Variables: *var-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000710 type() type of a variable
711 islocked() check if a variable is locked
Bram Moolenaar214641f2017-03-05 17:04:09 +0100712 funcref() get a Funcref for a function reference
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000713 function() get a Funcref for a function name
714 getbufvar() get a variable value from a specific buffer
715 setbufvar() set a variable in a specific buffer
Bram Moolenaarc6249bb2006-04-15 20:25:09 +0000716 getwinvar() get a variable from specific window
Bram Moolenaar06b5d512010-05-22 15:37:44 +0200717 gettabvar() get a variable from specific tab page
Bram Moolenaarc6249bb2006-04-15 20:25:09 +0000718 gettabwinvar() get a variable from specific window & tab page
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000719 setwinvar() set a variable in a specific window
Bram Moolenaar06b5d512010-05-22 15:37:44 +0200720 settabvar() set a variable in a specific tab page
Bram Moolenaarc6249bb2006-04-15 20:25:09 +0000721 settabwinvar() set a variable in a specific window & tab page
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000722 garbagecollect() possibly free memory
723
Bram Moolenaara3f41662010-07-11 19:01:06 +0200724Cursor and mark position: *cursor-functions* *mark-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000725 col() column number of the cursor or a mark
726 virtcol() screen column of the cursor or a mark
727 line() line number of the cursor or mark
728 wincol() window column number of the cursor
729 winline() window line number of the cursor
730 cursor() position the cursor at a line/column
Bram Moolenaar8d043172014-01-23 14:24:41 +0100731 screencol() get screen column of the cursor
732 screenrow() get screen row of the cursor
Bram Moolenaarb3d17a22019-07-07 18:28:14 +0200733 screenpos() screen row and col of a text character
Bram Moolenaar822ff862014-06-12 21:46:14 +0200734 getcurpos() get position of the cursor
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000735 getpos() get position of cursor, mark, etc.
736 setpos() set position of cursor, mark, etc.
Bram Moolenaarcfb4b472020-05-31 15:41:57 +0200737 getmarklist() list of global/local marks
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000738 byte2line() get line number at a specific byte count
739 line2byte() byte count at a specific line
740 diff_filler() get the number of filler lines above a line
Bram Moolenaar8d043172014-01-23 14:24:41 +0100741 screenattr() get attribute at a screen line/row
742 screenchar() get character code at a screen line/row
Bram Moolenaar2912abb2019-03-29 14:16:42 +0100743 screenchars() get character codes at a screen line/row
744 screenstring() get string of characters at a screen line/row
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000745
Bram Moolenaara3f41662010-07-11 19:01:06 +0200746Working with text in the current buffer: *text-functions*
Bram Moolenaar7c626922005-02-07 22:01:03 +0000747 getline() get a line or list of lines from the buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +0000748 setline() replace a line in the buffer
Bram Moolenaar7c626922005-02-07 22:01:03 +0000749 append() append line or list of lines in the buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +0000750 indent() indent of a specific line
751 cindent() indent according to C indenting
752 lispindent() indent according to Lisp indenting
753 nextnonblank() find next non-blank line
754 prevnonblank() find previous non-blank line
755 search() find a match for a pattern
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000756 searchpos() find a match for a pattern
Bram Moolenaarebacddb2020-06-04 15:22:21 +0200757 searchcount() get number of matches before/after the cursor
Bram Moolenaar071d4272004-06-13 20:20:40 +0000758 searchpair() find the other end of a start/skip/end
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000759 searchpairpos() find the other end of a start/skip/end
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000760 searchdecl() search for the declaration of a name
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200761 getcharsearch() return character search information
762 setcharsearch() set character search information
Bram Moolenaar071d4272004-06-13 20:20:40 +0000763
Bram Moolenaar931a2772019-07-04 16:54:54 +0200764Working with text in another buffer:
765 getbufline() get a list of lines from the specified buffer
766 setbufline() replace a line in the specified buffer
767 appendbufline() append a list of lines in the specified buffer
768 deletebufline() delete lines from a specified buffer
769
Bram Moolenaara3f41662010-07-11 19:01:06 +0200770 *system-functions* *file-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000771System functions and manipulation of files:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000772 glob() expand wildcards
773 globpath() expand wildcards in a number of directories
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200774 glob2regpat() convert a glob pattern into a search pattern
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000775 findfile() find a file in a list of directories
776 finddir() find a directory in a list of directories
Bram Moolenaar071d4272004-06-13 20:20:40 +0000777 resolve() find out where a shortcut points to
778 fnamemodify() modify a file name
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000779 pathshorten() shorten directory names in a path
780 simplify() simplify a path without changing its meaning
Bram Moolenaar071d4272004-06-13 20:20:40 +0000781 executable() check if an executable program exists
Bram Moolenaar7e38ea22014-04-05 22:55:53 +0200782 exepath() full path of an executable program
Bram Moolenaar071d4272004-06-13 20:20:40 +0000783 filereadable() check if a file can be read
784 filewritable() check if a file can be written to
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000785 getfperm() get the permissions of a file
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200786 setfperm() set the permissions of a file
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000787 getftype() get the kind of a file
Bram Moolenaar071d4272004-06-13 20:20:40 +0000788 isdirectory() check if a directory exists
Bram Moolenaar071d4272004-06-13 20:20:40 +0000789 getfsize() get the size of a file
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000790 getcwd() get the current working directory
Bram Moolenaar00aa0692019-04-27 20:37:57 +0200791 haslocaldir() check if current window used |:lcd| or |:tcd|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000792 tempname() get the name of a temporary file
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000793 mkdir() create a new directory
Bram Moolenaar1063f3d2019-05-07 22:06:52 +0200794 chdir() change current working directory
Bram Moolenaar071d4272004-06-13 20:20:40 +0000795 delete() delete a file
796 rename() rename a file
Bram Moolenaar7e38ea22014-04-05 22:55:53 +0200797 system() get the result of a shell command as a string
798 systemlist() get the result of a shell command as a list
Bram Moolenaar691ddee2019-05-09 14:52:41 +0200799 environ() get all environment variables
800 getenv() get one environment variable
801 setenv() set an environment variable
Bram Moolenaar071d4272004-06-13 20:20:40 +0000802 hostname() name of the system
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +0000803 readfile() read a file into a List of lines
Bram Moolenaar62e1bb42019-04-08 16:25:07 +0200804 readdir() get a List of file names in a directory
Bram Moolenaar6c9ba042020-06-01 16:09:41 +0200805 readdirex() get a List of file information in a directory
Bram Moolenaar314dd792019-02-03 15:27:20 +0100806 writefile() write a List of lines or Blob into a file
Bram Moolenaar071d4272004-06-13 20:20:40 +0000807
Bram Moolenaara3f41662010-07-11 19:01:06 +0200808Date and Time: *date-functions* *time-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000809 getftime() get last modification time of a file
810 localtime() get current time in seconds
811 strftime() convert time to a string
Bram Moolenaar10455d42019-11-21 15:36:18 +0100812 strptime() convert a date/time string to time
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000813 reltime() get the current or elapsed time accurately
814 reltimestr() convert reltime() result to a string
Bram Moolenaar03413f42016-04-12 21:07:15 +0200815 reltimefloat() convert reltime() result to a Float
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000816
Bram Moolenaara3f41662010-07-11 19:01:06 +0200817 *buffer-functions* *window-functions* *arg-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000818Buffers, windows and the argument list:
819 argc() number of entries in the argument list
820 argidx() current position in the argument list
Bram Moolenaar2d1fe052014-05-28 18:22:57 +0200821 arglistid() get id of the argument list
Bram Moolenaar071d4272004-06-13 20:20:40 +0000822 argv() get one entry from the argument list
Bram Moolenaar931a2772019-07-04 16:54:54 +0200823 bufadd() add a file to the list of buffers
Bram Moolenaar071d4272004-06-13 20:20:40 +0000824 bufexists() check if a buffer exists
825 buflisted() check if a buffer exists and is listed
Bram Moolenaar931a2772019-07-04 16:54:54 +0200826 bufload() ensure a buffer is loaded
Bram Moolenaar071d4272004-06-13 20:20:40 +0000827 bufloaded() check if a buffer exists and is loaded
828 bufname() get the name of a specific buffer
829 bufnr() get the buffer number of a specific buffer
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000830 tabpagebuflist() return List of buffers in a tab page
831 tabpagenr() get the number of a tab page
832 tabpagewinnr() like winnr() for a specified tab page
Bram Moolenaar071d4272004-06-13 20:20:40 +0000833 winnr() get the window number for the current window
Bram Moolenaar82af8712016-06-04 20:20:29 +0200834 bufwinid() get the window ID of a specific buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +0000835 bufwinnr() get the window number of a specific buffer
836 winbufnr() get the buffer number of a specific window
Bram Moolenaara3347722019-05-11 21:14:24 +0200837 listener_add() add a callback to listen to changes
Bram Moolenaar68e65602019-05-26 21:33:31 +0200838 listener_flush() invoke listener callbacks
Bram Moolenaara3347722019-05-11 21:14:24 +0200839 listener_remove() remove a listener callback
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200840 win_findbuf() find windows containing a buffer
841 win_getid() get window ID of a window
Bram Moolenaarebacddb2020-06-04 15:22:21 +0200842 win_gettype() get type of window
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200843 win_gotoid() go to window with ID
844 win_id2tabwin() get tab and window nr from window ID
845 win_id2win() get window nr from window ID
Bram Moolenaarebacddb2020-06-04 15:22:21 +0200846 win_splitmove() move window to a split of another window
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +0200847 getbufinfo() get a list with buffer information
848 gettabinfo() get a list with tab page information
849 getwininfo() get a list with window information
Bram Moolenaar07ad8162018-02-13 13:59:59 +0100850 getchangelist() get a list of change list entries
Bram Moolenaar4f505882018-02-10 21:06:32 +0100851 getjumplist() get a list of jump list entries
Bram Moolenaarfc65cab2018-08-28 22:58:02 +0200852 swapinfo() information about a swap file
Bram Moolenaarb730f0c2018-11-25 03:56:26 +0100853 swapname() get the swap file path of a buffer
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000854
Bram Moolenaara3f41662010-07-11 19:01:06 +0200855Command line: *command-line-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000856 getcmdline() get the current command line
857 getcmdpos() get position of the cursor in the command line
858 setcmdpos() set position of the cursor in the command line
859 getcmdtype() return the current command-line type
Bram Moolenaarfb539272014-08-22 19:21:47 +0200860 getcmdwintype() return the current command-line window type
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +0200861 getcompletion() list of command-line completion matches
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000862
Bram Moolenaara3f41662010-07-11 19:01:06 +0200863Quickfix and location lists: *quickfix-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000864 getqflist() list of quickfix errors
865 setqflist() modify a quickfix list
866 getloclist() list of location list items
867 setloclist() modify a location list
868
Bram Moolenaara3f41662010-07-11 19:01:06 +0200869Insert mode completion: *completion-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000870 complete() set found matches
871 complete_add() add to found matches
872 complete_check() check if completion should be aborted
Bram Moolenaarfd133322019-03-29 12:20:27 +0100873 complete_info() get current completion information
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000874 pumvisible() check if the popup menu is displayed
Bram Moolenaar5be4cee2019-09-27 19:34:08 +0200875 pum_getpos() position and size of popup menu if visible
Bram Moolenaar071d4272004-06-13 20:20:40 +0000876
Bram Moolenaara3f41662010-07-11 19:01:06 +0200877Folding: *folding-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000878 foldclosed() check for a closed fold at a specific line
879 foldclosedend() like foldclosed() but return the last line
880 foldlevel() check for the fold level at a specific line
881 foldtext() generate the line displayed for a closed fold
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000882 foldtextresult() get the text displayed for a closed fold
Bram Moolenaar071d4272004-06-13 20:20:40 +0000883
Bram Moolenaara3f41662010-07-11 19:01:06 +0200884Syntax and highlighting: *syntax-functions* *highlighting-functions*
Bram Moolenaar6ee10162007-07-26 20:58:42 +0000885 clearmatches() clear all matches defined by |matchadd()| and
886 the |:match| commands
887 getmatches() get all matches defined by |matchadd()| and
888 the |:match| commands
Bram Moolenaar071d4272004-06-13 20:20:40 +0000889 hlexists() check if a highlight group exists
890 hlID() get ID of a highlight group
891 synID() get syntax ID at a specific position
892 synIDattr() get a specific attribute of a syntax ID
893 synIDtrans() get translated syntax ID
Bram Moolenaar166af9b2010-11-16 20:34:40 +0100894 synstack() get list of syntax IDs at a specific position
Bram Moolenaar81af9252010-12-10 20:35:50 +0100895 synconcealed() get info about concealing
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000896 diff_hlID() get highlight ID for diff mode at a position
Bram Moolenaar6ee10162007-07-26 20:58:42 +0000897 matchadd() define a pattern to highlight (a "match")
Bram Moolenaarb3414592014-06-17 17:48:32 +0200898 matchaddpos() define a list of positions to highlight
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000899 matcharg() get info about |:match| arguments
Bram Moolenaar6ee10162007-07-26 20:58:42 +0000900 matchdelete() delete a match defined by |matchadd()| or a
901 |:match| command
902 setmatches() restore a list of matches saved by
903 |getmatches()|
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000904
Bram Moolenaara3f41662010-07-11 19:01:06 +0200905Spelling: *spell-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000906 spellbadword() locate badly spelled word at or after cursor
907 spellsuggest() return suggested spelling corrections
908 soundfold() return the sound-a-like equivalent of a word
Bram Moolenaar071d4272004-06-13 20:20:40 +0000909
Bram Moolenaara3f41662010-07-11 19:01:06 +0200910History: *history-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000911 histadd() add an item to a history
912 histdel() delete an item from a history
913 histget() get an item from a history
914 histnr() get highest index of a history list
915
Bram Moolenaara3f41662010-07-11 19:01:06 +0200916Interactive: *interactive-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000917 browse() put up a file requester
918 browsedir() put up a directory requester
Bram Moolenaar071d4272004-06-13 20:20:40 +0000919 confirm() let the user make a choice
920 getchar() get a character from the user
921 getcharmod() get modifiers for the last typed character
Bram Moolenaar09c6f262019-11-17 15:55:14 +0100922 getmousepos() get last known mouse position
Bram Moolenaarebacddb2020-06-04 15:22:21 +0200923 echoraw() output characters as-is
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000924 feedkeys() put characters in the typeahead queue
Bram Moolenaar071d4272004-06-13 20:20:40 +0000925 input() get a line from the user
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000926 inputlist() let the user pick an entry from a list
Bram Moolenaar071d4272004-06-13 20:20:40 +0000927 inputsecret() get a line from the user without showing it
928 inputdialog() get a line from the user in a dialog
Bram Moolenaar68b76a62005-03-25 21:53:48 +0000929 inputsave() save and clear typeahead
Bram Moolenaar071d4272004-06-13 20:20:40 +0000930 inputrestore() restore typeahead
931
Bram Moolenaara3f41662010-07-11 19:01:06 +0200932GUI: *gui-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000933 getfontname() get name of current font being used
Bram Moolenaarb5b75622018-03-09 22:22:21 +0100934 getwinpos() position of the Vim window
935 getwinposx() X position of the Vim window
936 getwinposy() Y position of the Vim window
Bram Moolenaar214641f2017-03-05 17:04:09 +0100937 balloon_show() set the balloon content
Bram Moolenaara2a80162017-11-21 23:09:50 +0100938 balloon_split() split a message for a balloon
Bram Moolenaar691ddee2019-05-09 14:52:41 +0200939 balloon_gettext() get the text in the balloon
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000940
Bram Moolenaara3f41662010-07-11 19:01:06 +0200941Vim server: *server-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000942 serverlist() return the list of server names
Bram Moolenaar01164a62017-11-02 22:58:42 +0100943 remote_startserver() run a server
Bram Moolenaar071d4272004-06-13 20:20:40 +0000944 remote_send() send command characters to a Vim server
945 remote_expr() evaluate an expression in a Vim server
946 server2client() send a reply to a client of a Vim server
947 remote_peek() check if there is a reply from a Vim server
948 remote_read() read a reply from a Vim server
949 foreground() move the Vim window to the foreground
950 remote_foreground() move the Vim server window to the foreground
951
Bram Moolenaara3f41662010-07-11 19:01:06 +0200952Window size and position: *window-size-functions*
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000953 winheight() get height of a specific window
954 winwidth() get width of a specific window
Bram Moolenaarf0b03c42017-12-17 17:17:07 +0100955 win_screenpos() get screen position of a window
Bram Moolenaarb730f0c2018-11-25 03:56:26 +0100956 winlayout() get layout of windows in a tab page
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000957 winrestcmd() return command to restore window sizes
958 winsaveview() get view of current window
959 winrestview() restore saved view of current window
960
Bram Moolenaar0eabd4d2020-03-15 16:13:53 +0100961Mappings and Menus: *mapping-functions*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000962 hasmapto() check if a mapping exists
963 mapcheck() check if a matching mapping exists
964 maparg() get rhs of a mapping
Bram Moolenaarebacddb2020-06-04 15:22:21 +0200965 mapset() restore a mapping
Bram Moolenaar0eabd4d2020-03-15 16:13:53 +0100966 menu_info() get information about a menu item
Bram Moolenaar26402cb2013-02-20 21:26:00 +0100967 wildmenumode() check if the wildmode is active
968
Bram Moolenaar683fa182015-11-30 21:38:24 +0100969Testing: *test-functions*
Bram Moolenaare18c0b32016-03-20 21:08:34 +0100970 assert_equal() assert that two expressions values are equal
Bram Moolenaarb730f0c2018-11-25 03:56:26 +0100971 assert_equalfile() assert that two file contents are equal
Bram Moolenaar03413f42016-04-12 21:07:15 +0200972 assert_notequal() assert that two expressions values are not equal
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +0200973 assert_inrange() assert that an expression is inside a range
Bram Moolenaar7db8f6f2016-03-29 23:12:46 +0200974 assert_match() assert that a pattern matches the value
Bram Moolenaar03413f42016-04-12 21:07:15 +0200975 assert_notmatch() assert that a pattern does not match the value
Bram Moolenaar683fa182015-11-30 21:38:24 +0100976 assert_false() assert that an expression is false
977 assert_true() assert that an expression is true
Bram Moolenaare18c0b32016-03-20 21:08:34 +0100978 assert_exception() assert that a command throws an exception
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +0100979 assert_beeps() assert that a command beeps
980 assert_fails() assert that a command fails
Bram Moolenaar3c2881d2017-03-21 19:18:29 +0100981 assert_report() report a test failure
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200982 test_alloc_fail() make memory allocation fail
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +0200983 test_autochdir() enable 'autochdir' during startup
Bram Moolenaar036986f2017-03-16 17:41:02 +0100984 test_override() test with Vim internal overrides
985 test_garbagecollect_now() free memory right now
Bram Moolenaarebacddb2020-06-04 15:22:21 +0200986 test_garbagecollect_soon() set a flag to free memory soon
Bram Moolenaar68e65602019-05-26 21:33:31 +0200987 test_getvalue() get value of an internal variable
Bram Moolenaar214641f2017-03-05 17:04:09 +0100988 test_ignore_error() ignore a specific error message
Bram Moolenaar314dd792019-02-03 15:27:20 +0100989 test_null_blob() return a null Blob
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200990 test_null_channel() return a null Channel
991 test_null_dict() return a null Dict
Bram Moolenaarebacddb2020-06-04 15:22:21 +0200992 test_null_function() return a null Funcref
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200993 test_null_job() return a null Job
994 test_null_list() return a null List
995 test_null_partial() return a null Partial function
996 test_null_string() return a null String
Bram Moolenaar214641f2017-03-05 17:04:09 +0100997 test_settime() set the time Vim uses internally
Bram Moolenaarbb8476b2019-05-04 15:47:48 +0200998 test_setmouse() set the mouse position
Bram Moolenaarb730f0c2018-11-25 03:56:26 +0100999 test_feedinput() add key sequence to input buffer
1000 test_option_not_set() reset flag indicating option was set
1001 test_scrollbar() simulate scrollbar movement in the GUI
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001002 test_refcount() return an expression's reference count
1003 test_srand_seed() set the seed value for srand()
1004 test_unknown() return a value with unknown type
1005 test_void() return a value with void type
Bram Moolenaar683fa182015-11-30 21:38:24 +01001006
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001007Inter-process communication: *channel-functions*
Bram Moolenaar51628222016-12-01 23:03:28 +01001008 ch_canread() check if there is something to read
Bram Moolenaar681baaf2016-02-04 20:57:07 +01001009 ch_open() open a channel
1010 ch_close() close a channel
Bram Moolenaar64d8e252016-09-06 22:12:34 +02001011 ch_close_in() close the in part of a channel
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001012 ch_read() read a message from a channel
Bram Moolenaard09091d2019-01-17 16:07:22 +01001013 ch_readblob() read a Blob from a channel
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001014 ch_readraw() read a raw message from a channel
Bram Moolenaar681baaf2016-02-04 20:57:07 +01001015 ch_sendexpr() send a JSON message over a channel
1016 ch_sendraw() send a raw message over a channel
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001017 ch_evalexpr() evaluate an expression over channel
1018 ch_evalraw() evaluate a raw string over channel
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001019 ch_status() get status of a channel
1020 ch_getbufnr() get the buffer number of a channel
1021 ch_getjob() get the job associated with a channel
1022 ch_info() get channel information
1023 ch_log() write a message in the channel log file
1024 ch_logfile() set the channel log file
1025 ch_setoptions() set the options for a channel
Bram Moolenaara02a5512016-06-17 12:48:11 +02001026 json_encode() encode an expression to a JSON string
1027 json_decode() decode a JSON string to Vim types
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001028 js_encode() encode an expression to a JSON string
1029 js_decode() decode a JSON string to Vim types
1030
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001031Jobs: *job-functions*
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001032 job_start() start a job
1033 job_stop() stop a job
1034 job_status() get the status of a job
1035 job_getchannel() get the channel used by a job
1036 job_info() get information about a job
1037 job_setoptions() set options for a job
1038
Bram Moolenaar162b7142018-12-21 15:17:36 +01001039Signs: *sign-functions*
1040 sign_define() define or update a sign
1041 sign_getdefined() get a list of defined signs
1042 sign_getplaced() get a list of placed signs
Bram Moolenaar6b7b7192019-01-11 13:42:41 +01001043 sign_jump() jump to a sign
Bram Moolenaar162b7142018-12-21 15:17:36 +01001044 sign_place() place a sign
Bram Moolenaar809ce4d2019-07-13 21:21:40 +02001045 sign_placelist() place a list of signs
Bram Moolenaar162b7142018-12-21 15:17:36 +01001046 sign_undefine() undefine a sign
1047 sign_unplace() unplace a sign
Bram Moolenaar809ce4d2019-07-13 21:21:40 +02001048 sign_unplacelist() unplace a list of signs
Bram Moolenaar162b7142018-12-21 15:17:36 +01001049
Bram Moolenaarc572da52017-08-27 16:52:01 +02001050Terminal window: *terminal-functions*
1051 term_start() open a terminal window and run a job
1052 term_list() get the list of terminal buffers
1053 term_sendkeys() send keystrokes to a terminal
1054 term_wait() wait for screen to be updated
1055 term_getjob() get the job associated with a terminal
1056 term_scrape() get row of a terminal screen
1057 term_getline() get a line of text from a terminal
1058 term_getattr() get the value of attribute {what}
1059 term_getcursor() get the cursor position of a terminal
1060 term_getscrolled() get the scroll count of a terminal
1061 term_getaltscreen() get the alternate screen flag
1062 term_getsize() get the size of a terminal
1063 term_getstatus() get the status of a terminal
1064 term_gettitle() get the title of a terminal
1065 term_gettty() get the tty name of a terminal
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02001066 term_setansicolors() set 16 ANSI colors, used for GUI
1067 term_getansicolors() get 16 ANSI colors, used for GUI
Bram Moolenaarb730f0c2018-11-25 03:56:26 +01001068 term_dumpdiff() display difference between two screen dumps
1069 term_dumpload() load a terminal screen dump in a window
1070 term_dumpwrite() dump contents of a terminal screen to a file
1071 term_setkill() set signal to stop job in a terminal
1072 term_setrestore() set command to restore a terminal
1073 term_setsize() set the size of a terminal
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001074 term_setapi() set terminal JSON API function name prefix
Bram Moolenaarc572da52017-08-27 16:52:01 +02001075
Bram Moolenaar931a2772019-07-04 16:54:54 +02001076Popup window: *popup-window-functions*
1077 popup_create() create popup centered in the screen
1078 popup_atcursor() create popup just above the cursor position,
1079 closes when the cursor moves away
Bram Moolenaarb3d17a22019-07-07 18:28:14 +02001080 popup_beval() at the position indicated by v:beval_
1081 variables, closes when the mouse moves away
Bram Moolenaar931a2772019-07-04 16:54:54 +02001082 popup_notification() show a notification for three seconds
1083 popup_dialog() create popup centered with padding and border
1084 popup_menu() prompt for selecting an item from a list
1085 popup_hide() hide a popup temporarily
1086 popup_show() show a previously hidden popup
1087 popup_move() change the position and size of a popup
1088 popup_setoptions() override options of a popup
1089 popup_settext() replace the popup buffer contents
1090 popup_close() close one popup
1091 popup_clear() close all popups
1092 popup_filter_menu() select from a list of items
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001093 popup_filter_yesno() block until 'y' or 'n' is pressed
Bram Moolenaar931a2772019-07-04 16:54:54 +02001094 popup_getoptions() get current options for a popup
1095 popup_getpos() get actual position and size of a popup
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001096 popup_findinfo() get window ID for popup info window
1097 popup_findpreview() get window ID for popup preview window
1098 popup_list() get list of all popup window IDs
1099 popup_locate() get popup window ID from its screen position
Bram Moolenaar931a2772019-07-04 16:54:54 +02001100
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001101Timers: *timer-functions*
1102 timer_start() create a timer
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02001103 timer_pause() pause or unpause a timer
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001104 timer_stop() stop a timer
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02001105 timer_stopall() stop all timers
1106 timer_info() get information about timers
Bram Moolenaar298b4402016-01-28 22:38:53 +01001107
Bram Moolenaarb730f0c2018-11-25 03:56:26 +01001108Tags: *tag-functions*
1109 taglist() get list of matching tags
1110 tagfiles() get a list of tags files
1111 gettagstack() get the tag stack of a window
1112 settagstack() modify the tag stack of a window
1113
1114Prompt Buffer: *promptbuffer-functions*
1115 prompt_setcallback() set prompt callback for a buffer
1116 prompt_setinterrupt() set interrupt callback for a buffer
1117 prompt_setprompt() set the prompt text for a buffer
1118
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001119Text Properties: *text-property-functions*
1120 prop_add() attach a property at a position
1121 prop_clear() remove all properties from a line or lines
1122 prop_find() search for a property
1123 prop_list() return a list of all properties in a line
1124 prop_remove() remove a property from a line
1125 prop_type_add() add/define a property type
1126 prop_type_change() change properties of a type
1127 prop_type_delete() remove a text property type
1128 prop_type_get() return the properties of a type
1129 prop_type_list() return a list of all property types
1130
1131Sound: *sound-functions*
1132 sound_clear() stop playing all sounds
1133 sound_playevent() play an event's sound
1134 sound_playfile() play a sound file
1135 sound_stop() stop playing a sound
1136
Bram Moolenaar26402cb2013-02-20 21:26:00 +01001137Various: *various-functions*
1138 mode() get current editing mode
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001139 state() get current busy state
Bram Moolenaar26402cb2013-02-20 21:26:00 +01001140 visualmode() last visual mode used
Bram Moolenaar071d4272004-06-13 20:20:40 +00001141 exists() check if a variable, function, etc. exists
1142 has() check if a feature is supported in Vim
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001143 changenr() return number of most recent change
Bram Moolenaar071d4272004-06-13 20:20:40 +00001144 cscope_connection() check if a cscope connection exists
1145 did_filetype() check if a FileType autocommand was used
1146 eventhandler() check if invoked by an event handler
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00001147 getpid() get process ID of Vim
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001148 getimstatus() check if IME status is active
1149 interrupt() interrupt script execution
1150 windowsversion() get MS-Windows version
Bram Moolenaar0c0eddd2020-06-13 15:47:25 +02001151 terminalprops() properties of the terminal
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001152
Bram Moolenaar071d4272004-06-13 20:20:40 +00001153 libcall() call a function in an external library
1154 libcallnr() idem, returning a number
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001155
Bram Moolenaar8d043172014-01-23 14:24:41 +01001156 undofile() get the name of the undo file
1157 undotree() return the state of the undo tree
1158
Bram Moolenaar071d4272004-06-13 20:20:40 +00001159 getreg() get contents of a register
Bram Moolenaarbb861e22020-06-07 18:16:36 +02001160 getreginfo() get information about a register
Bram Moolenaar071d4272004-06-13 20:20:40 +00001161 getregtype() get type of a register
1162 setreg() set contents and type of a register
Bram Moolenaar0b6d9112018-05-22 20:35:17 +02001163 reg_executing() return the name of the register being executed
1164 reg_recording() return the name of the register being recorded
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001165
Bram Moolenaar8d043172014-01-23 14:24:41 +01001166 shiftwidth() effective value of 'shiftwidth'
1167
Bram Moolenaar063b9d12016-07-09 20:21:48 +02001168 wordcount() get byte/word/char count of buffer
1169
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001170 luaeval() evaluate |Lua| expression
Bram Moolenaar7e506b62010-01-19 15:55:06 +01001171 mzeval() evaluate |MzScheme| expression
Bram Moolenaare9b892e2016-01-17 21:15:58 +01001172 perleval() evaluate Perl expression (|+perl|)
Bram Moolenaar8d043172014-01-23 14:24:41 +01001173 py3eval() evaluate Python expression (|+python3|)
1174 pyeval() evaluate Python expression (|+python|)
Bram Moolenaar690afe12017-01-28 18:34:47 +01001175 pyxeval() evaluate |python_x| expression
Bram Moolenaarebacddb2020-06-04 15:22:21 +02001176 rubyeval() evaluate |Ruby| expression
1177
Bram Moolenaar9d87a372018-12-18 21:41:50 +01001178 debugbreak() interrupt a program being debugged
Bram Moolenaar7e506b62010-01-19 15:55:06 +01001179
Bram Moolenaar071d4272004-06-13 20:20:40 +00001180==============================================================================
1181*41.7* Defining a function
1182
1183Vim enables you to define your own functions. The basic function declaration
1184begins as follows: >
1185
1186 :function {name}({var1}, {var2}, ...)
1187 : {body}
1188 :endfunction
1189<
1190 Note:
1191 Function names must begin with a capital letter.
1192
1193Let's define a short function to return the smaller of two numbers. It starts
1194with this line: >
1195
1196 :function Min(num1, num2)
1197
1198This tells Vim that the function is named "Min" and it takes two arguments:
1199"num1" and "num2".
1200 The first thing you need to do is to check to see which number is smaller:
1201 >
1202 : if a:num1 < a:num2
1203
1204The special prefix "a:" tells Vim that the variable is a function argument.
1205Let's assign the variable "smaller" the value of the smallest number: >
1206
1207 : if a:num1 < a:num2
1208 : let smaller = a:num1
1209 : else
1210 : let smaller = a:num2
1211 : endif
1212
1213The variable "smaller" is a local variable. Variables used inside a function
1214are local unless prefixed by something like "g:", "a:", or "s:".
1215
1216 Note:
1217 To access a global variable from inside a function you must prepend
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00001218 "g:" to it. Thus "g:today" inside a function is used for the global
1219 variable "today", and "today" is another variable, local to the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001220 function.
1221
1222You now use the ":return" statement to return the smallest number to the user.
1223Finally, you end the function: >
1224
1225 : return smaller
1226 :endfunction
1227
1228The complete function definition is as follows: >
1229
1230 :function Min(num1, num2)
1231 : if a:num1 < a:num2
1232 : let smaller = a:num1
1233 : else
1234 : let smaller = a:num2
1235 : endif
1236 : return smaller
1237 :endfunction
1238
Bram Moolenaar7c626922005-02-07 22:01:03 +00001239For people who like short functions, this does the same thing: >
1240
1241 :function Min(num1, num2)
1242 : if a:num1 < a:num2
1243 : return a:num1
1244 : endif
1245 : return a:num2
1246 :endfunction
1247
Bram Moolenaard1f56e62006-02-22 21:25:37 +00001248A user defined function is called in exactly the same way as a built-in
Bram Moolenaar071d4272004-06-13 20:20:40 +00001249function. Only the name is different. The Min function can be used like
1250this: >
1251
1252 :echo Min(5, 8)
1253
1254Only now will the function be executed and the lines be interpreted by Vim.
1255If there are mistakes, like using an undefined variable or function, you will
1256now get an error message. When defining the function these errors are not
1257detected.
1258
1259When a function reaches ":endfunction" or ":return" is used without an
1260argument, the function returns zero.
1261
1262To redefine a function that already exists, use the ! for the ":function"
1263command: >
1264
1265 :function! Min(num1, num2, num3)
1266
1267
1268USING A RANGE
1269
1270The ":call" command can be given a line range. This can have one of two
1271meanings. When a function has been defined with the "range" keyword, it will
1272take care of the line range itself.
1273 The function will be passed the variables "a:firstline" and "a:lastline".
1274These will have the line numbers from the range the function was called with.
1275Example: >
1276
1277 :function Count_words() range
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00001278 : let lnum = a:firstline
1279 : let n = 0
1280 : while lnum <= a:lastline
1281 : let n = n + len(split(getline(lnum)))
1282 : let lnum = lnum + 1
Bram Moolenaar071d4272004-06-13 20:20:40 +00001283 : endwhile
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00001284 : echo "found " . n . " words"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001285 :endfunction
1286
1287You can call this function with: >
1288
1289 :10,30call Count_words()
1290
1291It will be executed once and echo the number of words.
1292 The other way to use a line range is by defining a function without the
1293"range" keyword. The function will be called once for every line in the
1294range, with the cursor in that line. Example: >
1295
1296 :function Number()
1297 : echo "line " . line(".") . " contains: " . getline(".")
1298 :endfunction
1299
1300If you call this function with: >
1301
1302 :10,15call Number()
1303
1304The function will be called six times.
1305
1306
1307VARIABLE NUMBER OF ARGUMENTS
1308
1309Vim enables you to define functions that have a variable number of arguments.
1310The following command, for instance, defines a function that must have 1
1311argument (start) and can have up to 20 additional arguments: >
1312
1313 :function Show(start, ...)
1314
1315The variable "a:1" contains the first optional argument, "a:2" the second, and
1316so on. The variable "a:0" contains the number of extra arguments.
1317 For example: >
1318
1319 :function Show(start, ...)
1320 : echohl Title
Bram Moolenaar00654022011-02-25 14:42:19 +01001321 : echo "start is " . a:start
Bram Moolenaar071d4272004-06-13 20:20:40 +00001322 : echohl None
1323 : let index = 1
1324 : while index <= a:0
1325 : echo " Arg " . index . " is " . a:{index}
1326 : let index = index + 1
1327 : endwhile
1328 : echo ""
1329 :endfunction
1330
1331This uses the ":echohl" command to specify the highlighting used for the
1332following ":echo" command. ":echohl None" stops it again. The ":echon"
1333command works like ":echo", but doesn't output a line break.
1334
Bram Moolenaar7c626922005-02-07 22:01:03 +00001335You can also use the a:000 variable, it is a List of all the "..." arguments.
1336See |a:000|.
1337
Bram Moolenaar071d4272004-06-13 20:20:40 +00001338
1339LISTING FUNCTIONS
1340
1341The ":function" command lists the names and arguments of all user-defined
1342functions: >
1343
1344 :function
1345< function Show(start, ...) ~
1346 function GetVimIndent() ~
1347 function SetSyn(name) ~
1348
1349To see what a function does, use its name as an argument for ":function": >
1350
1351 :function SetSyn
1352< 1 if &syntax == '' ~
1353 2 let &syntax = a:name ~
1354 3 endif ~
1355 endfunction ~
1356
1357
1358DEBUGGING
1359
1360The line number is useful for when you get an error message or when debugging.
1361See |debug-scripts| about debugging mode.
1362 You can also set the 'verbose' option to 12 or higher to see all function
1363calls. Set it to 15 or higher to see every executed line.
1364
1365
1366DELETING A FUNCTION
1367
1368To delete the Show() function: >
1369
1370 :delfunction Show
1371
1372You get an error when the function doesn't exist.
1373
Bram Moolenaar7c626922005-02-07 22:01:03 +00001374
1375FUNCTION REFERENCES
1376
1377Sometimes it can be useful to have a variable point to one function or
1378another. You can do it with the function() function. It turns the name of a
1379function into a reference: >
1380
1381 :let result = 0 " or 1
1382 :function! Right()
1383 : return 'Right!'
1384 :endfunc
1385 :function! Wrong()
1386 : return 'Wrong!'
1387 :endfunc
1388 :
1389 :if result == 1
1390 : let Afunc = function('Right')
1391 :else
1392 : let Afunc = function('Wrong')
1393 :endif
1394 :echo call(Afunc, [])
1395< Wrong! ~
1396
1397Note that the name of a variable that holds a function reference must start
1398with a capital. Otherwise it could be confused with the name of a builtin
1399function.
1400 The way to invoke a function that a variable refers to is with the call()
1401function. Its first argument is the function reference, the second argument
1402is a List with arguments.
1403
1404Function references are most useful in combination with a Dictionary, as is
1405explained in the next section.
1406
Bram Moolenaar071d4272004-06-13 20:20:40 +00001407==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00001408*41.8* Lists and Dictionaries
1409
1410So far we have used the basic types String and Number. Vim also supports two
1411composite types: List and Dictionary.
1412
1413A List is an ordered sequence of things. The things can be any kind of value,
1414thus you can make a List of numbers, a List of Lists and even a List of mixed
1415items. To create a List with three strings: >
1416
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001417 :let alist = ['aap', 'mies', 'noot']
Bram Moolenaar7c626922005-02-07 22:01:03 +00001418
1419The List items are enclosed in square brackets and separated by commas. To
1420create an empty List: >
1421
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001422 :let alist = []
Bram Moolenaar7c626922005-02-07 22:01:03 +00001423
1424You can add items to a List with the add() function: >
1425
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001426 :let alist = []
Bram Moolenaar7c626922005-02-07 22:01:03 +00001427 :call add(alist, 'foo')
1428 :call add(alist, 'bar')
1429 :echo alist
1430< ['foo', 'bar'] ~
1431
1432List concatenation is done with +: >
1433
1434 :echo alist + ['foo', 'bar']
1435< ['foo', 'bar', 'foo', 'bar'] ~
1436
1437Or, if you want to extend a List directly: >
1438
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001439 :let alist = ['one']
Bram Moolenaar7c626922005-02-07 22:01:03 +00001440 :call extend(alist, ['two', 'three'])
1441 :echo alist
1442< ['one', 'two', 'three'] ~
1443
1444Notice that using add() will have a different effect: >
1445
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001446 :let alist = ['one']
Bram Moolenaar7c626922005-02-07 22:01:03 +00001447 :call add(alist, ['two', 'three'])
1448 :echo alist
1449< ['one', ['two', 'three']] ~
1450
1451The second argument of add() is added as a single item.
1452
1453
1454FOR LOOP
1455
1456One of the nice things you can do with a List is iterate over it: >
1457
1458 :let alist = ['one', 'two', 'three']
1459 :for n in alist
1460 : echo n
1461 :endfor
1462< one ~
1463 two ~
1464 three ~
1465
1466This will loop over each element in List "alist", assigning the value to
1467variable "n". The generic form of a for loop is: >
1468
1469 :for {varname} in {listexpression}
1470 : {commands}
1471 :endfor
1472
1473To loop a certain number of times you need a List of a specific length. The
1474range() function creates one for you: >
1475
1476 :for a in range(3)
1477 : echo a
1478 :endfor
1479< 0 ~
1480 1 ~
1481 2 ~
1482
1483Notice that the first item of the List that range() produces is zero, thus the
1484last item is one less than the length of the list.
1485 You can also specify the maximum value, the stride and even go backwards: >
1486
1487 :for a in range(8, 4, -2)
1488 : echo a
1489 :endfor
1490< 8 ~
1491 6 ~
1492 4 ~
1493
1494A more useful example, looping over lines in the buffer: >
1495
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001496 :for line in getline(1, 20)
1497 : if line =~ "Date: "
1498 : echo matchstr(line, 'Date: \zs.*')
1499 : endif
1500 :endfor
Bram Moolenaar7c626922005-02-07 22:01:03 +00001501
1502This looks into lines 1 to 20 (inclusive) and echoes any date found in there.
1503
1504
1505DICTIONARIES
1506
1507A Dictionary stores key-value pairs. You can quickly lookup a value if you
1508know the key. A Dictionary is created with curly braces: >
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001509
Bram Moolenaar7c626922005-02-07 22:01:03 +00001510 :let uk2nl = {'one': 'een', 'two': 'twee', 'three': 'drie'}
1511
Bram Moolenaar4399ef42005-02-12 14:29:27 +00001512Now you can lookup words by putting the key in square brackets: >
Bram Moolenaar7c626922005-02-07 22:01:03 +00001513
1514 :echo uk2nl['two']
1515< twee ~
1516
1517The generic form for defining a Dictionary is: >
1518
1519 {<key> : <value>, ...}
1520
1521An empty Dictionary is one without any keys: >
1522
1523 {}
1524
1525The possibilities with Dictionaries are numerous. There are various functions
1526for them as well. For example, you can obtain a list of the keys and loop
1527over them: >
1528
1529 :for key in keys(uk2nl)
1530 : echo key
1531 :endfor
1532< three ~
1533 one ~
1534 two ~
1535
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00001536You will notice the keys are not ordered. You can sort the list to get a
Bram Moolenaar7c626922005-02-07 22:01:03 +00001537specific order: >
1538
1539 :for key in sort(keys(uk2nl))
1540 : echo key
1541 :endfor
1542< one ~
1543 three ~
1544 two ~
1545
1546But you can never get back the order in which items are defined. For that you
1547need to use a List, it stores items in an ordered sequence.
1548
1549
1550DICTIONARY FUNCTIONS
1551
1552The items in a Dictionary can normally be obtained with an index in square
1553brackets: >
1554
1555 :echo uk2nl['one']
1556< een ~
1557
1558A method that does the same, but without so many punctuation characters: >
1559
1560 :echo uk2nl.one
1561< een ~
1562
1563This only works for a key that is made of ASCII letters, digits and the
1564underscore. You can also assign a new value this way: >
1565
1566 :let uk2nl.four = 'vier'
1567 :echo uk2nl
1568< {'three': 'drie', 'four': 'vier', 'one': 'een', 'two': 'twee'} ~
1569
1570And now for something special: you can directly define a function and store a
1571reference to it in the dictionary: >
1572
1573 :function uk2nl.translate(line) dict
1574 : return join(map(split(a:line), 'get(self, v:val, "???")'))
1575 :endfunction
1576
1577Let's first try it out: >
1578
1579 :echo uk2nl.translate('three two five one')
1580< drie twee ??? een ~
1581
1582The first special thing you notice is the "dict" at the end of the ":function"
1583line. This marks the function as being used from a Dictionary. The "self"
1584local variable will then refer to that Dictionary.
1585 Now let's break up the complicated return command: >
1586
1587 split(a:line)
1588
Bram Moolenaar00654022011-02-25 14:42:19 +01001589The split() function takes a string, chops it into whitespace separated words
Bram Moolenaar7c626922005-02-07 22:01:03 +00001590and returns a list with these words. Thus in the example it returns: >
1591
1592 :echo split('three two five one')
1593< ['three', 'two', 'five', 'one'] ~
1594
1595This list is the first argument to the map() function. This will go through
1596the list, evaluating its second argument with "v:val" set to the value of each
1597item. This is a shortcut to using a for loop. This command: >
1598
1599 :let alist = map(split(a:line), 'get(self, v:val, "???")')
1600
1601Is equivalent to: >
1602
1603 :let alist = split(a:line)
1604 :for idx in range(len(alist))
1605 : let alist[idx] = get(self, alist[idx], "???")
1606 :endfor
1607
1608The get() function checks if a key is present in a Dictionary. If it is, then
1609the value is retrieved. If it isn't, then the default value is returned, in
Bram Moolenaar4399ef42005-02-12 14:29:27 +00001610the example it's '???'. This is a convenient way to handle situations where a
Bram Moolenaar7c626922005-02-07 22:01:03 +00001611key may not be present and you don't want an error message.
1612
1613The join() function does the opposite of split(): it joins together a list of
1614words, putting a space in between.
1615 This combination of split(), map() and join() is a nice way to filter a line
1616of words in a very compact way.
1617
1618
1619OBJECT ORIENTED PROGRAMMING
1620
1621Now that you can put both values and functions in a Dictionary, you can
1622actually use a Dictionary like an object.
1623 Above we used a Dictionary for translating Dutch to English. We might want
1624to do the same for other languages. Let's first make an object (aka
1625Dictionary) that has the translate function, but no words to translate: >
1626
1627 :let transdict = {}
1628 :function transdict.translate(line) dict
1629 : return join(map(split(a:line), 'get(self.words, v:val, "???")'))
1630 :endfunction
1631
1632It's slightly different from the function above, using 'self.words' to lookup
1633word translations. But we don't have a self.words. Thus you could call this
1634an abstract class.
1635
1636Now we can instantiate a Dutch translation object: >
1637
1638 :let uk2nl = copy(transdict)
1639 :let uk2nl.words = {'one': 'een', 'two': 'twee', 'three': 'drie'}
1640 :echo uk2nl.translate('three one')
1641< drie een ~
1642
1643And a German translator: >
1644
1645 :let uk2de = copy(transdict)
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001646 :let uk2de.words = {'one': 'eins', 'two': 'zwei', 'three': 'drei'}
Bram Moolenaar7c626922005-02-07 22:01:03 +00001647 :echo uk2de.translate('three one')
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001648< drei eins ~
Bram Moolenaar7c626922005-02-07 22:01:03 +00001649
1650You see that the copy() function is used to make a copy of the "transdict"
1651Dictionary and then the copy is changed to add the words. The original
1652remains the same, of course.
1653
1654Now you can go one step further, and use your preferred translator: >
1655
1656 :if $LANG =~ "de"
1657 : let trans = uk2de
1658 :else
1659 : let trans = uk2nl
1660 :endif
1661 :echo trans.translate('one two three')
1662< een twee drie ~
1663
1664Here "trans" refers to one of the two objects (Dictionaries). No copy is
1665made. More about List and Dictionary identity can be found at |list-identity|
1666and |dict-identity|.
1667
1668Now you might use a language that isn't supported. You can overrule the
1669translate() function to do nothing: >
1670
1671 :let uk2uk = copy(transdict)
1672 :function! uk2uk.translate(line)
1673 : return a:line
1674 :endfunction
1675 :echo uk2uk.translate('three one wladiwostok')
1676< three one wladiwostok ~
1677
1678Notice that a ! was used to overwrite the existing function reference. Now
1679use "uk2uk" when no recognized language is found: >
1680
1681 :if $LANG =~ "de"
1682 : let trans = uk2de
1683 :elseif $LANG =~ "nl"
1684 : let trans = uk2nl
1685 :else
1686 : let trans = uk2uk
1687 :endif
1688 :echo trans.translate('one two three')
1689< one two three ~
1690
1691For further reading see |Lists| and |Dictionaries|.
1692
1693==============================================================================
1694*41.9* Exceptions
Bram Moolenaar071d4272004-06-13 20:20:40 +00001695
1696Let's start with an example: >
1697
1698 :try
1699 : read ~/templates/pascal.tmpl
1700 :catch /E484:/
1701 : echo "Sorry, the Pascal template file cannot be found."
1702 :endtry
1703
1704The ":read" command will fail if the file does not exist. Instead of
1705generating an error message, this code catches the error and gives the user a
Bram Moolenaar00654022011-02-25 14:42:19 +01001706nice message.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001707
1708For the commands in between ":try" and ":endtry" errors are turned into
1709exceptions. An exception is a string. In the case of an error the string
1710contains the error message. And every error message has a number. In this
1711case, the error we catch contains "E484:". This number is guaranteed to stay
1712the same (the text may change, e.g., it may be translated).
1713
1714When the ":read" command causes another error, the pattern "E484:" will not
1715match in it. Thus this exception will not be caught and result in the usual
1716error message.
1717
1718You might be tempted to do this: >
1719
1720 :try
1721 : read ~/templates/pascal.tmpl
1722 :catch
1723 : echo "Sorry, the Pascal template file cannot be found."
1724 :endtry
1725
1726This means all errors are caught. But then you will not see errors that are
1727useful, such as "E21: Cannot make changes, 'modifiable' is off".
1728
1729Another useful mechanism is the ":finally" command: >
1730
1731 :let tmp = tempname()
1732 :try
1733 : exe ".,$write " . tmp
1734 : exe "!filter " . tmp
1735 : .,$delete
1736 : exe "$read " . tmp
1737 :finally
1738 : call delete(tmp)
1739 :endtry
1740
1741This filters the lines from the cursor until the end of the file through the
1742"filter" command, which takes a file name argument. No matter if the
1743filtering works, something goes wrong in between ":try" and ":finally" or the
1744user cancels the filtering by pressing CTRL-C, the "call delete(tmp)" is
1745always executed. This makes sure you don't leave the temporary file behind.
1746
1747More information about exception handling can be found in the reference
1748manual: |exception-handling|.
1749
1750==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00001751*41.10* Various remarks
Bram Moolenaar071d4272004-06-13 20:20:40 +00001752
1753Here is a summary of items that apply to Vim scripts. They are also mentioned
1754elsewhere, but form a nice checklist.
1755
1756The end-of-line character depends on the system. For Unix a single <NL>
Bram Moolenaar6f345a12019-12-17 21:27:18 +01001757character is used. For MS-Windows and the like, <CR><LF> is used. This is
1758important when using mappings that end in a <CR>. See |:source_crnl|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001759
1760
1761WHITE SPACE
1762
1763Blank lines are allowed and ignored.
1764
1765Leading whitespace characters (blanks and TABs) are always ignored. The
Bram Moolenaar214641f2017-03-05 17:04:09 +01001766whitespaces between parameters (e.g. between the "set" and the "cpoptions" in
Bram Moolenaar071d4272004-06-13 20:20:40 +00001767the example below) are reduced to one blank character and plays the role of a
1768separator, the whitespaces after the last (visible) character may or may not
1769be ignored depending on the situation, see below.
1770
1771For a ":set" command involving the "=" (equal) sign, such as in: >
1772
1773 :set cpoptions =aABceFst
1774
1775the whitespace immediately before the "=" sign is ignored. But there can be
1776no whitespace after the "=" sign!
1777
1778To include a whitespace character in the value of an option, it must be
1779escaped by a "\" (backslash) as in the following example: >
1780
1781 :set tags=my\ nice\ file
1782
Bram Moolenaar00654022011-02-25 14:42:19 +01001783The same example written as: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001784
1785 :set tags=my nice file
1786
1787will issue an error, because it is interpreted as: >
1788
1789 :set tags=my
1790 :set nice
1791 :set file
1792
1793
1794COMMENTS
1795
1796The character " (the double quote mark) starts a comment. Everything after
1797and including this character until the end-of-line is considered a comment and
1798is ignored, except for commands that don't consider comments, as shown in
1799examples below. A comment can start on any character position on the line.
1800
1801There is a little "catch" with comments for some commands. Examples: >
1802
1803 :abbrev dev development " shorthand
1804 :map <F3> o#include " insert include
1805 :execute cmd " do it
1806 :!ls *.c " list C files
1807
1808The abbreviation 'dev' will be expanded to 'development " shorthand'. The
1809mapping of <F3> will actually be the whole line after the 'o# ....' including
1810the '" insert include'. The "execute" command will give an error. The "!"
1811command will send everything after it to the shell, causing an error for an
1812unmatched '"' character.
1813 There can be no comment after ":map", ":abbreviate", ":execute" and "!"
1814commands (there are a few more commands with this restriction). For the
1815":map", ":abbreviate" and ":execute" commands there is a trick: >
1816
1817 :abbrev dev development|" shorthand
1818 :map <F3> o#include|" insert include
1819 :execute cmd |" do it
1820
1821With the '|' character the command is separated from the next one. And that
Bram Moolenaar9e1d2832007-05-06 12:51:41 +00001822next command is only a comment. For the last command you need to do two
1823things: |:execute| and use '|': >
1824 :exe '!ls *.c' |" list C files
Bram Moolenaar071d4272004-06-13 20:20:40 +00001825
1826Notice that there is no white space before the '|' in the abbreviation and
1827mapping. For these commands, any character until the end-of-line or '|' is
1828included. As a consequence of this behavior, you don't always see that
1829trailing whitespace is included: >
1830
1831 :map <F4> o#include
1832
Bram Moolenaar9e1d2832007-05-06 12:51:41 +00001833To spot these problems, you can set the 'list' option when editing vimrc
Bram Moolenaar071d4272004-06-13 20:20:40 +00001834files.
1835
Bram Moolenaar9e1d2832007-05-06 12:51:41 +00001836For Unix there is one special way to comment a line, that allows making a Vim
1837script executable: >
1838 #!/usr/bin/env vim -S
1839 echo "this is a Vim script"
1840 quit
1841
1842The "#" command by itself lists a line with the line number. Adding an
1843exclamation mark changes it into doing nothing, so that you can add the shell
1844command to execute the rest of the file. |:#!| |-S|
1845
Bram Moolenaar071d4272004-06-13 20:20:40 +00001846
1847PITFALLS
1848
1849Even bigger problem arises in the following example: >
1850
1851 :map ,ab o#include
1852 :unmap ,ab
1853
1854Here the unmap command will not work, because it tries to unmap ",ab ". This
1855does not exist as a mapped sequence. An error will be issued, which is very
1856hard to identify, because the ending whitespace character in ":unmap ,ab " is
1857not visible.
1858
1859And this is the same as what happens when one uses a comment after an 'unmap'
1860command: >
1861
1862 :unmap ,ab " comment
1863
1864Here the comment part will be ignored. However, Vim will try to unmap
1865',ab ', which does not exist. Rewrite it as: >
1866
1867 :unmap ,ab| " comment
1868
1869
1870RESTORING THE VIEW
1871
Bram Moolenaar3a0d8092012-10-21 03:02:54 +02001872Sometimes you want to make a change and go back to where the cursor was.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001873Restoring the relative position would also be nice, so that the same line
1874appears at the top of the window.
1875 This example yanks the current line, puts it above the first line in the
1876file and then restores the view: >
1877
1878 map ,p ma"aYHmbgg"aP`bzt`a
1879
1880What this does: >
1881 ma"aYHmbgg"aP`bzt`a
1882< ma set mark a at cursor position
1883 "aY yank current line into register a
1884 Hmb go to top line in window and set mark b there
1885 gg go to first line in file
1886 "aP put the yanked line above it
1887 `b go back to top line in display
1888 zt position the text in the window as before
1889 `a go back to saved cursor position
1890
1891
1892PACKAGING
1893
1894To avoid your function names to interfere with functions that you get from
1895others, use this scheme:
1896- Prepend a unique string before each function name. I often use an
1897 abbreviation. For example, "OW_" is used for the option window functions.
1898- Put the definition of your functions together in a file. Set a global
1899 variable to indicate that the functions have been loaded. When sourcing the
1900 file again, first unload the functions.
1901Example: >
1902
1903 " This is the XXX package
1904
1905 if exists("XXX_loaded")
1906 delfun XXX_one
1907 delfun XXX_two
1908 endif
1909
1910 function XXX_one(a)
1911 ... body of function ...
1912 endfun
1913
1914 function XXX_two(b)
1915 ... body of function ...
1916 endfun
1917
1918 let XXX_loaded = 1
1919
1920==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00001921*41.11* Writing a plugin *write-plugin*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001922
1923You can write a Vim script in such a way that many people can use it. This is
1924called a plugin. Vim users can drop your script in their plugin directory and
1925use its features right away |add-plugin|.
1926
1927There are actually two types of plugins:
1928
1929 global plugins: For all types of files.
1930filetype plugins: Only for files of a specific type.
1931
1932In this section the first type is explained. Most items are also relevant for
1933writing filetype plugins. The specifics for filetype plugins are in the next
1934section |write-filetype-plugin|.
1935
1936
1937NAME
1938
1939First of all you must choose a name for your plugin. The features provided
1940by the plugin should be clear from its name. And it should be unlikely that
1941someone else writes a plugin with the same name but which does something
1942different. And please limit the name to 8 characters, to avoid problems on
Bram Moolenaar6f345a12019-12-17 21:27:18 +01001943old MS-Windows systems.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001944
1945A script that corrects typing mistakes could be called "typecorr.vim". We
1946will use it here as an example.
1947
1948For the plugin to work for everybody, it should follow a few guidelines. This
1949will be explained step-by-step. The complete example plugin is at the end.
1950
1951
1952BODY
1953
1954Let's start with the body of the plugin, the lines that do the actual work: >
1955
1956 14 iabbrev teh the
1957 15 iabbrev otehr other
1958 16 iabbrev wnat want
1959 17 iabbrev synchronisation
1960 18 \ synchronization
1961 19 let s:count = 4
1962
1963The actual list should be much longer, of course.
1964
1965The line numbers have only been added to explain a few things, don't put them
1966in your plugin file!
1967
1968
1969HEADER
1970
1971You will probably add new corrections to the plugin and soon have several
Bram Moolenaard09acef2012-09-21 14:54:30 +02001972versions lying around. And when distributing this file, people will want to
Bram Moolenaar071d4272004-06-13 20:20:40 +00001973know who wrote this wonderful plugin and where they can send remarks.
1974Therefore, put a header at the top of your plugin: >
1975
1976 1 " Vim global plugin for correcting typing mistakes
1977 2 " Last Change: 2000 Oct 15
1978 3 " Maintainer: Bram Moolenaar <Bram@vim.org>
1979
1980About copyright and licensing: Since plugins are very useful and it's hardly
1981worth restricting their distribution, please consider making your plugin
1982either public domain or use the Vim |license|. A short note about this near
1983the top of the plugin should be sufficient. Example: >
1984
1985 4 " License: This file is placed in the public domain.
1986
1987
1988LINE CONTINUATION, AVOIDING SIDE EFFECTS *use-cpo-save*
1989
1990In line 18 above, the line-continuation mechanism is used |line-continuation|.
1991Users with 'compatible' set will run into trouble here, they will get an error
1992message. We can't just reset 'compatible', because that has a lot of side
1993effects. To avoid this, we will set the 'cpoptions' option to its Vim default
1994value and restore it later. That will allow the use of line-continuation and
1995make the script work for most people. It is done like this: >
1996
1997 11 let s:save_cpo = &cpo
1998 12 set cpo&vim
1999 ..
2000 42 let &cpo = s:save_cpo
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02002001 43 unlet s:save_cpo
Bram Moolenaar071d4272004-06-13 20:20:40 +00002002
2003We first store the old value of 'cpoptions' in the s:save_cpo variable. At
2004the end of the plugin this value is restored.
2005
2006Notice that a script-local variable is used |s:var|. A global variable could
2007already be in use for something else. Always use script-local variables for
2008things that are only used in the script.
2009
2010
2011NOT LOADING
2012
2013It's possible that a user doesn't always want to load this plugin. Or the
2014system administrator has dropped it in the system-wide plugin directory, but a
2015user has his own plugin he wants to use. Then the user must have a chance to
2016disable loading this specific plugin. This will make it possible: >
2017
Bram Moolenaarc5604bc2010-07-17 15:20:30 +02002018 6 if exists("g:loaded_typecorr")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002019 7 finish
2020 8 endif
Bram Moolenaarc5604bc2010-07-17 15:20:30 +02002021 9 let g:loaded_typecorr = 1
Bram Moolenaar071d4272004-06-13 20:20:40 +00002022
2023This also avoids that when the script is loaded twice it would cause error
2024messages for redefining functions and cause trouble for autocommands that are
2025added twice.
2026
Bram Moolenaarc5604bc2010-07-17 15:20:30 +02002027The name is recommended to start with "loaded_" and then the file name of the
2028plugin, literally. The "g:" is prepended just to avoid mistakes when using
2029the variable in a function (without "g:" it would be a variable local to the
2030function).
2031
2032Using "finish" stops Vim from reading the rest of the file, it's much quicker
2033than using if-endif around the whole file.
2034
Bram Moolenaar071d4272004-06-13 20:20:40 +00002035
2036MAPPING
2037
2038Now let's make the plugin more interesting: We will add a mapping that adds a
2039correction for the word under the cursor. We could just pick a key sequence
2040for this mapping, but the user might already use it for something else. To
2041allow the user to define which keys a mapping in a plugin uses, the <Leader>
2042item can be used: >
2043
2044 22 map <unique> <Leader>a <Plug>TypecorrAdd
2045
2046The "<Plug>TypecorrAdd" thing will do the work, more about that further on.
2047
2048The user can set the "mapleader" variable to the key sequence that he wants
2049this mapping to start with. Thus if the user has done: >
2050
2051 let mapleader = "_"
2052
2053the mapping will define "_a". If the user didn't do this, the default value
2054will be used, which is a backslash. Then a map for "\a" will be defined.
2055
2056Note that <unique> is used, this will cause an error message if the mapping
2057already happened to exist. |:map-<unique>|
2058
2059But what if the user wants to define his own key sequence? We can allow that
2060with this mechanism: >
2061
2062 21 if !hasmapto('<Plug>TypecorrAdd')
2063 22 map <unique> <Leader>a <Plug>TypecorrAdd
2064 23 endif
2065
2066This checks if a mapping to "<Plug>TypecorrAdd" already exists, and only
2067defines the mapping from "<Leader>a" if it doesn't. The user then has a
2068chance of putting this in his vimrc file: >
2069
2070 map ,c <Plug>TypecorrAdd
2071
2072Then the mapped key sequence will be ",c" instead of "_a" or "\a".
2073
2074
2075PIECES
2076
2077If a script gets longer, you often want to break up the work in pieces. You
2078can use functions or mappings for this. But you don't want these functions
2079and mappings to interfere with the ones from other scripts. For example, you
2080could define a function Add(), but another script could try to define the same
2081function. To avoid this, we define the function local to the script by
2082prepending it with "s:".
2083
2084We will define a function that adds a new typing correction: >
2085
2086 30 function s:Add(from, correct)
2087 31 let to = input("type the correction for " . a:from . ": ")
2088 32 exe ":iabbrev " . a:from . " " . to
2089 ..
2090 36 endfunction
2091
2092Now we can call the function s:Add() from within this script. If another
2093script also defines s:Add(), it will be local to that script and can only
2094be called from the script it was defined in. There can also be a global Add()
2095function (without the "s:"), which is again another function.
2096
2097<SID> can be used with mappings. It generates a script ID, which identifies
2098the current script. In our typing correction plugin we use it like this: >
2099
2100 24 noremap <unique> <script> <Plug>TypecorrAdd <SID>Add
2101 ..
2102 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), 1)<CR>
2103
2104Thus when a user types "\a", this sequence is invoked: >
2105
2106 \a -> <Plug>TypecorrAdd -> <SID>Add -> :call <SID>Add()
2107
2108If another script would also map <SID>Add, it would get another script ID and
2109thus define another mapping.
2110
2111Note that instead of s:Add() we use <SID>Add() here. That is because the
2112mapping is typed by the user, thus outside of the script. The <SID> is
2113translated to the script ID, so that Vim knows in which script to look for
2114the Add() function.
2115
2116This is a bit complicated, but it's required for the plugin to work together
2117with other plugins. The basic rule is that you use <SID>Add() in mappings and
2118s:Add() in other places (the script itself, autocommands, user commands).
2119
2120We can also add a menu entry to do the same as the mapping: >
2121
2122 26 noremenu <script> Plugin.Add\ Correction <SID>Add
2123
2124The "Plugin" menu is recommended for adding menu items for plugins. In this
2125case only one item is used. When adding more items, creating a submenu is
2126recommended. For example, "Plugin.CVS" could be used for a plugin that offers
2127CVS operations "Plugin.CVS.checkin", "Plugin.CVS.checkout", etc.
2128
2129Note that in line 28 ":noremap" is used to avoid that any other mappings cause
2130trouble. Someone may have remapped ":call", for example. In line 24 we also
2131use ":noremap", but we do want "<SID>Add" to be remapped. This is why
2132"<script>" is used here. This only allows mappings which are local to the
2133script. |:map-<script>| The same is done in line 26 for ":noremenu".
2134|:menu-<script>|
2135
2136
2137<SID> AND <Plug> *using-<Plug>*
2138
2139Both <SID> and <Plug> are used to avoid that mappings of typed keys interfere
2140with mappings that are only to be used from other mappings. Note the
2141difference between using <SID> and <Plug>:
2142
2143<Plug> is visible outside of the script. It is used for mappings which the
2144 user might want to map a key sequence to. <Plug> is a special code
2145 that a typed key will never produce.
2146 To make it very unlikely that other plugins use the same sequence of
2147 characters, use this structure: <Plug> scriptname mapname
2148 In our example the scriptname is "Typecorr" and the mapname is "Add".
2149 This results in "<Plug>TypecorrAdd". Only the first character of
2150 scriptname and mapname is uppercase, so that we can see where mapname
2151 starts.
2152
2153<SID> is the script ID, a unique identifier for a script.
2154 Internally Vim translates <SID> to "<SNR>123_", where "123" can be any
2155 number. Thus a function "<SID>Add()" will have a name "<SNR>11_Add()"
2156 in one script, and "<SNR>22_Add()" in another. You can see this if
2157 you use the ":function" command to get a list of functions. The
2158 translation of <SID> in mappings is exactly the same, that's how you
2159 can call a script-local function from a mapping.
2160
2161
2162USER COMMAND
2163
2164Now let's add a user command to add a correction: >
2165
2166 38 if !exists(":Correct")
2167 39 command -nargs=1 Correct :call s:Add(<q-args>, 0)
2168 40 endif
2169
2170The user command is defined only if no command with the same name already
2171exists. Otherwise we would get an error here. Overriding the existing user
2172command with ":command!" is not a good idea, this would probably make the user
2173wonder why the command he defined himself doesn't work. |:command|
2174
2175
2176SCRIPT VARIABLES
2177
2178When a variable starts with "s:" it is a script variable. It can only be used
2179inside a script. Outside the script it's not visible. This avoids trouble
2180with using the same variable name in different scripts. The variables will be
2181kept as long as Vim is running. And the same variables are used when sourcing
2182the same script again. |s:var|
2183
2184The fun is that these variables can also be used in functions, autocommands
2185and user commands that are defined in the script. In our example we can add
2186a few lines to count the number of corrections: >
2187
2188 19 let s:count = 4
2189 ..
2190 30 function s:Add(from, correct)
2191 ..
2192 34 let s:count = s:count + 1
2193 35 echo s:count . " corrections now"
2194 36 endfunction
2195
2196First s:count is initialized to 4 in the script itself. When later the
2197s:Add() function is called, it increments s:count. It doesn't matter from
2198where the function was called, since it has been defined in the script, it
2199will use the local variables from this script.
2200
2201
2202THE RESULT
2203
2204Here is the resulting complete example: >
2205
2206 1 " Vim global plugin for correcting typing mistakes
2207 2 " Last Change: 2000 Oct 15
2208 3 " Maintainer: Bram Moolenaar <Bram@vim.org>
2209 4 " License: This file is placed in the public domain.
2210 5
Bram Moolenaarc5604bc2010-07-17 15:20:30 +02002211 6 if exists("g:loaded_typecorr")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002212 7 finish
2213 8 endif
Bram Moolenaarc5604bc2010-07-17 15:20:30 +02002214 9 let g:loaded_typecorr = 1
Bram Moolenaar071d4272004-06-13 20:20:40 +00002215 10
2216 11 let s:save_cpo = &cpo
2217 12 set cpo&vim
2218 13
2219 14 iabbrev teh the
2220 15 iabbrev otehr other
2221 16 iabbrev wnat want
2222 17 iabbrev synchronisation
2223 18 \ synchronization
2224 19 let s:count = 4
2225 20
2226 21 if !hasmapto('<Plug>TypecorrAdd')
2227 22 map <unique> <Leader>a <Plug>TypecorrAdd
2228 23 endif
2229 24 noremap <unique> <script> <Plug>TypecorrAdd <SID>Add
2230 25
2231 26 noremenu <script> Plugin.Add\ Correction <SID>Add
2232 27
2233 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), 1)<CR>
2234 29
2235 30 function s:Add(from, correct)
2236 31 let to = input("type the correction for " . a:from . ": ")
2237 32 exe ":iabbrev " . a:from . " " . to
2238 33 if a:correct | exe "normal viws\<C-R>\" \b\e" | endif
2239 34 let s:count = s:count + 1
2240 35 echo s:count . " corrections now"
2241 36 endfunction
2242 37
2243 38 if !exists(":Correct")
2244 39 command -nargs=1 Correct :call s:Add(<q-args>, 0)
2245 40 endif
2246 41
2247 42 let &cpo = s:save_cpo
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02002248 43 unlet s:save_cpo
Bram Moolenaar071d4272004-06-13 20:20:40 +00002249
2250Line 33 wasn't explained yet. It applies the new correction to the word under
2251the cursor. The |:normal| command is used to use the new abbreviation. Note
2252that mappings and abbreviations are expanded here, even though the function
2253was called from a mapping defined with ":noremap".
2254
2255Using "unix" for the 'fileformat' option is recommended. The Vim scripts will
2256then work everywhere. Scripts with 'fileformat' set to "dos" do not work on
2257Unix. Also see |:source_crnl|. To be sure it is set right, do this before
2258writing the file: >
2259
2260 :set fileformat=unix
2261
2262
2263DOCUMENTATION *write-local-help*
2264
2265It's a good idea to also write some documentation for your plugin. Especially
2266when its behavior can be changed by the user. See |add-local-help| for how
2267they are installed.
2268
2269Here is a simple example for a plugin help file, called "typecorr.txt": >
2270
2271 1 *typecorr.txt* Plugin for correcting typing mistakes
2272 2
2273 3 If you make typing mistakes, this plugin will have them corrected
2274 4 automatically.
2275 5
2276 6 There are currently only a few corrections. Add your own if you like.
2277 7
2278 8 Mappings:
2279 9 <Leader>a or <Plug>TypecorrAdd
2280 10 Add a correction for the word under the cursor.
2281 11
2282 12 Commands:
2283 13 :Correct {word}
2284 14 Add a correction for {word}.
2285 15
2286 16 *typecorr-settings*
2287 17 This plugin doesn't have any settings.
2288
2289The first line is actually the only one for which the format matters. It will
2290be extracted from the help file to be put in the "LOCAL ADDITIONS:" section of
2291help.txt |local-additions|. The first "*" must be in the first column of the
2292first line. After adding your help file do ":help" and check that the entries
2293line up nicely.
2294
2295You can add more tags inside ** in your help file. But be careful not to use
2296existing help tags. You would probably use the name of your plugin in most of
2297them, like "typecorr-settings" in the example.
2298
2299Using references to other parts of the help in || is recommended. This makes
2300it easy for the user to find associated help.
2301
2302
2303FILETYPE DETECTION *plugin-filetype*
2304
2305If your filetype is not already detected by Vim, you should create a filetype
2306detection snippet in a separate file. It is usually in the form of an
2307autocommand that sets the filetype when the file name matches a pattern.
2308Example: >
2309
2310 au BufNewFile,BufRead *.foo set filetype=foofoo
2311
2312Write this single-line file as "ftdetect/foofoo.vim" in the first directory
2313that appears in 'runtimepath'. For Unix that would be
2314"~/.vim/ftdetect/foofoo.vim". The convention is to use the name of the
2315filetype for the script name.
2316
2317You can make more complicated checks if you like, for example to inspect the
2318contents of the file to recognize the language. Also see |new-filetype|.
2319
2320
2321SUMMARY *plugin-special*
2322
2323Summary of special things to use in a plugin:
2324
2325s:name Variables local to the script.
2326
2327<SID> Script-ID, used for mappings and functions local to
2328 the script.
2329
2330hasmapto() Function to test if the user already defined a mapping
2331 for functionality the script offers.
2332
2333<Leader> Value of "mapleader", which the user defines as the
2334 keys that plugin mappings start with.
2335
2336:map <unique> Give a warning if a mapping already exists.
2337
2338:noremap <script> Use only mappings local to the script, not global
2339 mappings.
2340
2341exists(":Cmd") Check if a user command already exists.
2342
2343==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00002344*41.12* Writing a filetype plugin *write-filetype-plugin* *ftplugin*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002345
2346A filetype plugin is like a global plugin, except that it sets options and
2347defines mappings for the current buffer only. See |add-filetype-plugin| for
2348how this type of plugin is used.
2349
Bram Moolenaar7c626922005-02-07 22:01:03 +00002350First read the section on global plugins above |41.11|. All that is said there
Bram Moolenaar071d4272004-06-13 20:20:40 +00002351also applies to filetype plugins. There are a few extras, which are explained
2352here. The essential thing is that a filetype plugin should only have an
2353effect on the current buffer.
2354
2355
2356DISABLING
2357
2358If you are writing a filetype plugin to be used by many people, they need a
2359chance to disable loading it. Put this at the top of the plugin: >
2360
2361 " Only do this when not done yet for this buffer
2362 if exists("b:did_ftplugin")
2363 finish
2364 endif
2365 let b:did_ftplugin = 1
2366
2367This also needs to be used to avoid that the same plugin is executed twice for
2368the same buffer (happens when using an ":edit" command without arguments).
2369
2370Now users can disable loading the default plugin completely by making a
2371filetype plugin with only this line: >
2372
2373 let b:did_ftplugin = 1
2374
2375This does require that the filetype plugin directory comes before $VIMRUNTIME
2376in 'runtimepath'!
2377
2378If you do want to use the default plugin, but overrule one of the settings,
2379you can write the different setting in a script: >
2380
2381 setlocal textwidth=70
2382
2383Now write this in the "after" directory, so that it gets sourced after the
2384distributed "vim.vim" ftplugin |after-directory|. For Unix this would be
2385"~/.vim/after/ftplugin/vim.vim". Note that the default plugin will have set
2386"b:did_ftplugin", but it is ignored here.
2387
2388
2389OPTIONS
2390
2391To make sure the filetype plugin only affects the current buffer use the >
2392
2393 :setlocal
2394
2395command to set options. And only set options which are local to a buffer (see
2396the help for the option to check that). When using |:setlocal| for global
2397options or options local to a window, the value will change for many buffers,
2398and that is not what a filetype plugin should do.
2399
2400When an option has a value that is a list of flags or items, consider using
2401"+=" and "-=" to keep the existing value. Be aware that the user may have
2402changed an option value already. First resetting to the default value and
Bram Moolenaard58e9292011-02-09 17:07:58 +01002403then changing it is often a good idea. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002404
2405 :setlocal formatoptions& formatoptions+=ro
2406
2407
2408MAPPINGS
2409
2410To make sure mappings will only work in the current buffer use the >
2411
2412 :map <buffer>
2413
2414command. This needs to be combined with the two-step mapping explained above.
2415An example of how to define functionality in a filetype plugin: >
2416
2417 if !hasmapto('<Plug>JavaImport')
2418 map <buffer> <unique> <LocalLeader>i <Plug>JavaImport
2419 endif
2420 noremap <buffer> <unique> <Plug>JavaImport oimport ""<Left><Esc>
2421
2422|hasmapto()| is used to check if the user has already defined a map to
2423<Plug>JavaImport. If not, then the filetype plugin defines the default
2424mapping. This starts with |<LocalLeader>|, which allows the user to select
2425the key(s) he wants filetype plugin mappings to start with. The default is a
2426backslash.
2427"<unique>" is used to give an error message if the mapping already exists or
2428overlaps with an existing mapping.
2429|:noremap| is used to avoid that any other mappings that the user has defined
2430interferes. You might want to use ":noremap <script>" to allow remapping
2431mappings defined in this script that start with <SID>.
2432
2433The user must have a chance to disable the mappings in a filetype plugin,
2434without disabling everything. Here is an example of how this is done for a
2435plugin for the mail filetype: >
2436
2437 " Add mappings, unless the user didn't want this.
2438 if !exists("no_plugin_maps") && !exists("no_mail_maps")
2439 " Quote text by inserting "> "
2440 if !hasmapto('<Plug>MailQuote')
2441 vmap <buffer> <LocalLeader>q <Plug>MailQuote
2442 nmap <buffer> <LocalLeader>q <Plug>MailQuote
2443 endif
2444 vnoremap <buffer> <Plug>MailQuote :s/^/> /<CR>
2445 nnoremap <buffer> <Plug>MailQuote :.,$s/^/> /<CR>
2446 endif
2447
2448Two global variables are used:
Bram Moolenaare0720cb2017-03-29 13:48:40 +02002449|no_plugin_maps| disables mappings for all filetype plugins
2450|no_mail_maps| disables mappings for the "mail" filetype
Bram Moolenaar071d4272004-06-13 20:20:40 +00002451
2452
2453USER COMMANDS
2454
2455To add a user command for a specific file type, so that it can only be used in
2456one buffer, use the "-buffer" argument to |:command|. Example: >
2457
2458 :command -buffer Make make %:r.s
2459
2460
2461VARIABLES
2462
2463A filetype plugin will be sourced for each buffer of the type it's for. Local
2464script variables |s:var| will be shared between all invocations. Use local
2465buffer variables |b:var| if you want a variable specifically for one buffer.
2466
2467
2468FUNCTIONS
2469
2470When defining a function, this only needs to be done once. But the filetype
2471plugin will be sourced every time a file with this filetype will be opened.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02002472This construct makes sure the function is only defined once: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002473
2474 :if !exists("*s:Func")
2475 : function s:Func(arg)
2476 : ...
2477 : endfunction
2478 :endif
2479<
2480
Bram Moolenaar38a55632016-02-15 22:07:32 +01002481UNDO *undo_indent* *undo_ftplugin*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002482
2483When the user does ":setfiletype xyz" the effect of the previous filetype
2484should be undone. Set the b:undo_ftplugin variable to the commands that will
2485undo the settings in your filetype plugin. Example: >
2486
2487 let b:undo_ftplugin = "setlocal fo< com< tw< commentstring<"
2488 \ . "| unlet b:match_ignorecase b:match_words b:match_skip"
2489
2490Using ":setlocal" with "<" after the option name resets the option to its
2491global value. That is mostly the best way to reset the option value.
2492
2493This does require removing the "C" flag from 'cpoptions' to allow line
2494continuation, as mentioned above |use-cpo-save|.
2495
Bram Moolenaar38a55632016-02-15 22:07:32 +01002496For undoing the effect of an indent script, the b:undo_indent variable should
2497be set accordingly.
2498
Bram Moolenaar071d4272004-06-13 20:20:40 +00002499
2500FILE NAME
2501
2502The filetype must be included in the file name |ftplugin-name|. Use one of
2503these three forms:
2504
2505 .../ftplugin/stuff.vim
2506 .../ftplugin/stuff_foo.vim
2507 .../ftplugin/stuff/bar.vim
2508
2509"stuff" is the filetype, "foo" and "bar" are arbitrary names.
2510
2511
2512SUMMARY *ftplugin-special*
2513
2514Summary of special things to use in a filetype plugin:
2515
2516<LocalLeader> Value of "maplocalleader", which the user defines as
2517 the keys that filetype plugin mappings start with.
2518
2519:map <buffer> Define a mapping local to the buffer.
2520
2521:noremap <script> Only remap mappings defined in this script that start
2522 with <SID>.
2523
2524:setlocal Set an option for the current buffer only.
2525
2526:command -buffer Define a user command local to the buffer.
2527
2528exists("*s:Func") Check if a function was already defined.
2529
2530Also see |plugin-special|, the special things used for all plugins.
2531
2532==============================================================================
Bram Moolenaar7c626922005-02-07 22:01:03 +00002533*41.13* Writing a compiler plugin *write-compiler-plugin*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002534
2535A compiler plugin sets options for use with a specific compiler. The user can
2536load it with the |:compiler| command. The main use is to set the
2537'errorformat' and 'makeprg' options.
2538
2539Easiest is to have a look at examples. This command will edit all the default
2540compiler plugins: >
2541
2542 :next $VIMRUNTIME/compiler/*.vim
2543
2544Use |:next| to go to the next plugin file.
2545
2546There are two special items about these files. First is a mechanism to allow
2547a user to overrule or add to the default file. The default files start with: >
2548
2549 :if exists("current_compiler")
2550 : finish
2551 :endif
2552 :let current_compiler = "mine"
2553
2554When you write a compiler file and put it in your personal runtime directory
2555(e.g., ~/.vim/compiler for Unix), you set the "current_compiler" variable to
2556make the default file skip the settings.
Bram Moolenaarc6039d82005-12-02 00:44:04 +00002557 *:CompilerSet*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002558The second mechanism is to use ":set" for ":compiler!" and ":setlocal" for
2559":compiler". Vim defines the ":CompilerSet" user command for this. However,
2560older Vim versions don't, thus your plugin should define it then. This is an
2561example: >
2562
2563 if exists(":CompilerSet") != 2
2564 command -nargs=* CompilerSet setlocal <args>
2565 endif
2566 CompilerSet errorformat& " use the default 'errorformat'
2567 CompilerSet makeprg=nmake
2568
2569When you write a compiler plugin for the Vim distribution or for a system-wide
2570runtime directory, use the mechanism mentioned above. When
2571"current_compiler" was already set by a user plugin nothing will be done.
2572
2573When you write a compiler plugin to overrule settings from a default plugin,
2574don't check "current_compiler". This plugin is supposed to be loaded
2575last, thus it should be in a directory at the end of 'runtimepath'. For Unix
2576that could be ~/.vim/after/compiler.
2577
2578==============================================================================
Bram Moolenaar05159a02005-02-26 23:04:13 +00002579*41.14* Writing a plugin that loads quickly *write-plugin-quickload*
2580
2581A plugin may grow and become quite long. The startup delay may become
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00002582noticeable, while you hardly ever use the plugin. Then it's time for a
Bram Moolenaar05159a02005-02-26 23:04:13 +00002583quickload plugin.
2584
2585The basic idea is that the plugin is loaded twice. The first time user
2586commands and mappings are defined that offer the functionality. The second
2587time the functions that implement the functionality are defined.
2588
2589It may sound surprising that quickload means loading a script twice. What we
2590mean is that it loads quickly the first time, postponing the bulk of the
2591script to the second time, which only happens when you actually use it. When
2592you always use the functionality it actually gets slower!
2593
Bram Moolenaar76916e62006-03-21 21:23:25 +00002594Note that since Vim 7 there is an alternative: use the |autoload|
2595functionality |41.15|.
2596
Bram Moolenaar05159a02005-02-26 23:04:13 +00002597The following example shows how it's done: >
2598
2599 " Vim global plugin for demonstrating quick loading
2600 " Last Change: 2005 Feb 25
2601 " Maintainer: Bram Moolenaar <Bram@vim.org>
2602 " License: This file is placed in the public domain.
2603
2604 if !exists("s:did_load")
2605 command -nargs=* BNRead call BufNetRead(<f-args>)
2606 map <F19> :call BufNetWrite('something')<CR>
2607
2608 let s:did_load = 1
2609 exe 'au FuncUndefined BufNet* source ' . expand('<sfile>')
2610 finish
2611 endif
2612
2613 function BufNetRead(...)
2614 echo 'BufNetRead(' . string(a:000) . ')'
2615 " read functionality here
2616 endfunction
2617
2618 function BufNetWrite(...)
2619 echo 'BufNetWrite(' . string(a:000) . ')'
2620 " write functionality here
2621 endfunction
2622
2623When the script is first loaded "s:did_load" is not set. The commands between
2624the "if" and "endif" will be executed. This ends in a |:finish| command, thus
2625the rest of the script is not executed.
2626
2627The second time the script is loaded "s:did_load" exists and the commands
2628after the "endif" are executed. This defines the (possible long)
2629BufNetRead() and BufNetWrite() functions.
2630
2631If you drop this script in your plugin directory Vim will execute it on
2632startup. This is the sequence of events that happens:
2633
26341. The "BNRead" command is defined and the <F19> key is mapped when the script
2635 is sourced at startup. A |FuncUndefined| autocommand is defined. The
2636 ":finish" command causes the script to terminate early.
2637
26382. The user types the BNRead command or presses the <F19> key. The
2639 BufNetRead() or BufNetWrite() function will be called.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00002640
Bram Moolenaar05159a02005-02-26 23:04:13 +000026413. Vim can't find the function and triggers the |FuncUndefined| autocommand
2642 event. Since the pattern "BufNet*" matches the invoked function, the
2643 command "source fname" will be executed. "fname" will be equal to the name
2644 of the script, no matter where it is located, because it comes from
2645 expanding "<sfile>" (see |expand()|).
2646
26474. The script is sourced again, the "s:did_load" variable exists and the
2648 functions are defined.
2649
2650Notice that the functions that are loaded afterwards match the pattern in the
2651|FuncUndefined| autocommand. You must make sure that no other plugin defines
2652functions that match this pattern.
2653
2654==============================================================================
2655*41.15* Writing library scripts *write-library-script*
2656
2657Some functionality will be required in several places. When this becomes more
2658than a few lines you will want to put it in one script and use it from many
2659scripts. We will call that one script a library script.
2660
2661Manually loading a library script is possible, so long as you avoid loading it
2662when it's already done. You can do this with the |exists()| function.
2663Example: >
2664
2665 if !exists('*MyLibFunction')
2666 runtime library/mylibscript.vim
2667 endif
2668 call MyLibFunction(arg)
2669
2670Here you need to know that MyLibFunction() is defined in a script
2671"library/mylibscript.vim" in one of the directories in 'runtimepath'.
2672
2673To make this a bit simpler Vim offers the autoload mechanism. Then the
2674example looks like this: >
2675
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002676 call mylib#myfunction(arg)
Bram Moolenaar05159a02005-02-26 23:04:13 +00002677
2678That's a lot simpler, isn't it? Vim will recognize the function name and when
2679it's not defined search for the script "autoload/mylib.vim" in 'runtimepath'.
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002680That script must define the "mylib#myfunction()" function.
Bram Moolenaar05159a02005-02-26 23:04:13 +00002681
2682You can put many other functions in the mylib.vim script, you are free to
2683organize your functions in library scripts. But you must use function names
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00002684where the part before the '#' matches the script name. Otherwise Vim would
2685not know what script to load.
Bram Moolenaar05159a02005-02-26 23:04:13 +00002686
Bram Moolenaard1f56e62006-02-22 21:25:37 +00002687If you get really enthusiastic and write lots of library scripts, you may
Bram Moolenaar05159a02005-02-26 23:04:13 +00002688want to use subdirectories. Example: >
2689
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002690 call netlib#ftp#read('somefile')
Bram Moolenaar05159a02005-02-26 23:04:13 +00002691
2692For Unix the library script used for this could be:
2693
2694 ~/.vim/autoload/netlib/ftp.vim
2695
2696Where the function is defined like this: >
2697
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002698 function netlib#ftp#read(fname)
Bram Moolenaar05159a02005-02-26 23:04:13 +00002699 " Read the file fname through ftp
2700 endfunction
2701
2702Notice that the name the function is defined with is exactly the same as the
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00002703name used for calling the function. And the part before the last '#'
Bram Moolenaar05159a02005-02-26 23:04:13 +00002704exactly matches the subdirectory and script name.
2705
2706You can use the same mechanism for variables: >
2707
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002708 let weekdays = dutch#weekdays
Bram Moolenaar05159a02005-02-26 23:04:13 +00002709
2710This will load the script "autoload/dutch.vim", which should contain something
2711like: >
2712
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002713 let dutch#weekdays = ['zondag', 'maandag', 'dinsdag', 'woensdag',
Bram Moolenaar05159a02005-02-26 23:04:13 +00002714 \ 'donderdag', 'vrijdag', 'zaterdag']
2715
2716Further reading: |autoload|.
2717
2718==============================================================================
Bram Moolenaar76916e62006-03-21 21:23:25 +00002719*41.16* Distributing Vim scripts *distribute-script*
2720
2721Vim users will look for scripts on the Vim website: http://www.vim.org.
2722If you made something that is useful for others, share it!
2723
2724Vim scripts can be used on any system. There might not be a tar or gzip
2725command. If you want to pack files together and/or compress them the "zip"
2726utility is recommended.
2727
2728For utmost portability use Vim itself to pack scripts together. This can be
2729done with the Vimball utility. See |vimball|.
2730
Bram Moolenaarc01140a2006-03-24 22:21:52 +00002731It's good if you add a line to allow automatic updating. See |glvs-plugins|.
2732
Bram Moolenaar76916e62006-03-21 21:23:25 +00002733==============================================================================
Bram Moolenaar071d4272004-06-13 20:20:40 +00002734
2735Next chapter: |usr_42.txt| Add new menus
2736
Bram Moolenaard473c8c2018-08-11 18:00:22 +02002737Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: