From aed8ce9da277f5ecffe968b324f242c41c3b752a Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 10:50:31 +0200 Subject: Adding upstream version 2:9.0.1378. Signed-off-by: Daniel Baumann --- runtime/doc/usr_51.txt | 694 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 694 insertions(+) create mode 100644 runtime/doc/usr_51.txt (limited to 'runtime/doc/usr_51.txt') diff --git a/runtime/doc/usr_51.txt b/runtime/doc/usr_51.txt new file mode 100644 index 0000000..2eea6aa --- /dev/null +++ b/runtime/doc/usr_51.txt @@ -0,0 +1,694 @@ +*usr_51.txt* For Vim version 9.0. 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 his own plugin he wants 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 he wants +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 his 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 his 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