Edit: /usr/share/vim/vim91/doc/usr_51.txt (25517B)
*usr_51.txt* For Vim version 9.1. Last change: 2022 Jun 03
VIM USER MANUAL - by Bram Moolenaar
Write plugins
Plugins can be used to define settings for a specific type of file, syntax
highlighting and many other things. This chapter explains how to write the
most common Vim plugins.
|51.1| Writing a generic plugin
|51.2| Writing a filetype plugin
|51.3| Writing a compiler plugin
|51.4| Distributing Vim scripts
Next chapter: |usr_52.txt| Write large plugins
Previous chapter: |usr_50.txt| Advanced Vim script writing
Table of contents: |usr_toc.txt|
==============================================================================
*51.1* Writing a generic plugin *write-plugin*
You can write a Vim script in such a way that many people can use it. This is
called a plugin. Vim users can drop your script in their plugin directory and
use its features right away |add-plugin|.
There are actually two types of plugins:
global plugins: For all types of files.
filetype plugins: Only for files of a specific type.
In this section the first type is explained. Most items are also relevant for
writing filetype plugins. The specifics for filetype plugins are in the next
section |write-filetype-plugin|.
We will use |Vim9| syntax here, the recommended way to write new plugins.
Make sure the file starts with the `vim9script` command.
NAME
First of all you must choose a name for your plugin. The features provided
by the plugin should be clear from its name. And it should be unlikely that
someone else writes a plugin with the same name but which does something
different.
A script that corrects typing mistakes could be called "typecorrect.vim". We
will use it here as an example.
For the plugin to work for everybody, it should follow a few guidelines. This
will be explained step-by-step. The complete example plugin is at the end.
BODY
Let's start with the body of the plugin, the lines that do the actual work: >
12 iabbrev teh the
13 iabbrev otehr other
14 iabbrev wnat want
15 iabbrev synchronisation
16 \ synchronization
The actual list should be much longer, of course.
The line numbers have only been added to explain a few things, don't put them
in your plugin file!
FIRST LINE
>
1 vim9script noclear
You need to use `vim9script` as the very first command. Best is to put it in
the very first line.
The script we are writing will have a `finish` command to bail out when it is
loaded a second time. To avoid that the items defined in the script are lost
the "noclear" argument is used. More info about this at |vim9-reload|.
HEADER
You will probably add new corrections to the plugin and soon have several
versions lying around. And when distributing this file, people will want to
know who wrote this wonderful plugin and where they can send remarks.
Therefore, put a header at the top of your plugin: >
2 # Vim global plugin for correcting typing mistakes
3 # Last Change: 2021 Dec 30
4 # Maintainer: Bram Moolenaar
About copyright and licensing: Since plugins are very useful and it's hardly
worth restricting their distribution, please consider making your plugin
either public domain or use the Vim |license|. A short note about this near
the top of the plugin should be sufficient. Example: >
5 # License: This file is placed in the public domain.
NOT LOADING
It is possible that a user doesn't always want to load this plugin. Or the
system administrator has dropped it in the system-wide plugin directory, but a
user has their own plugin they want to use. Then the user must have a chance
to disable loading this specific plugin. These lines will make it possible: >
7 if exists("g:loaded_typecorrect")
8 finish
9 endif
10 g:loaded_typecorrect = 1
This also avoids that when the script is loaded twice it would pointlessly
redefine functions and cause trouble for autocommands that are added twice.
The name is recommended to start with "g:loaded_" and then the file name of
the plugin, literally. The "g:" is prepended to make the variable global, so
that other places can check whether its functionality is available. Without
"g:" it would be local to the script.
Using `finish` stops Vim from reading the rest of the file, it's much quicker
than using if-endif around the whole file, since Vim would still need to parse
the commands to find the `endif`.
MAPPING
Now let's make the plugin more interesting: We will add a mapping that adds a
correction for the word under the cursor. We could just pick a key sequence
for this mapping, but the user might already use it for something else. To
allow the user to define which keys a mapping in a plugin uses, the
item can be used: >
20 map a TypecorrAdd;
The "TypecorrAdd;" thing will do the work, more about that further on.
The user can set the "g:mapleader" variable to the key sequence that they want
plugin mappings to start with. Thus if the user has done: >
g:mapleader = "_"
the mapping will define "_a". If the user didn't do this, the default value
will be used, which is a backslash. Then a map for "\a" will be defined.
Note that is used, this will cause an error message if the mapping
already happened to exist. |:map-|
But what if the user wants to define their own key sequence? We can allow
that with this mechanism: >
19 if !hasmapto('TypecorrAdd;')
20 map a TypecorrAdd;
21 endif
This checks if a mapping to "TypecorrAdd;" already exists, and only
defines the mapping from "a" if it doesn't. The user then has a
chance of putting this in their vimrc file: >
map ,c TypecorrAdd;
Then the mapped key sequence will be ",c" instead of "_a" or "\a".
PIECES
If a script gets longer, you often want to break up the work in pieces. You
can use functions or mappings for this. But you don't want these functions
and mappings to interfere with the ones from other scripts. For example, you
could define a function Add(), but another script could try to define the same
function. To avoid this, we define the function local to the script.
Fortunately, in |Vim9| script this is the default. In a legacy script you
would need to prefix the name with "s:".
We will define a function that adds a new typing correction: >
28 def Add(from: string, correct: bool)
29 var to = input($"type the correction for {from}: ")
30 exe $":iabbrev {from} {to}"
...
34 enddef
Now we can call the function Add() from within this script. If another
script also defines Add(), it will be local to that script and can only
be called from that script. There can also be a global g:Add() function,
which is again another function.
can be used with mappings. It generates a script ID, which identifies
the current script. In our typing correction plugin we use it like this: >
22 noremap