Mercurial > vim
annotate runtime/doc/usr_51.txt @ 28933:57c9377b9c62
Update runtime files.
Commit: https://github.com/vim/vim/commit/2d8ed0203aedd5f6c22efa99394a3677c17c7a7a
Author: Bram Moolenaar <Bram@vim.org>
Date: Sat May 21 13:08:16 2022 +0100
Update runtime files.
author | Bram Moolenaar <Bram@vim.org> |
---|---|
date | Sat, 21 May 2022 14:15:05 +0200 |
parents | 82244cfc4694 |
children | f8e9d5023bf6 |
rev | line source |
---|---|
28933 | 1 *usr_51.txt* For Vim version 8.2. Last change: 2022 May 14 |
28862
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
2 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
3 VIM USER MANUAL - by Bram Moolenaar |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
4 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
5 Write plugins |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
6 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
7 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
8 Plugins can be used to define settings for a specific type of file, syntax |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
9 highlighting and many other things. This chapter explains how to write the |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
10 most common Vim plugins. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
11 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
12 |51.1| Writing a generic plugin |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
13 |51.2| Writing a filetype plugin |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
14 |51.3| Writing a compiler plugin |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
15 |51.4| Writing a plugin that loads quickly |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
16 |51.5| Writing library scripts |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
17 |51.6| Distributing Vim scripts |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
18 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
19 Next chapter: |usr_52.txt| Write plugins using Vim9 script |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
20 Previous chapter: |usr_50.txt| Advanced Vim script writing |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
21 Table of contents: |usr_toc.txt| |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
22 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
23 ============================================================================== |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
24 *51.1* Writing a generic plugin *write-plugin* |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
25 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
26 You can write a Vim script in such a way that many people can use it. This is |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
27 called a plugin. Vim users can drop your script in their plugin directory and |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
28 use its features right away |add-plugin|. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
29 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
30 There are actually two types of plugins: |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
31 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
32 global plugins: For all types of files. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
33 filetype plugins: Only for files of a specific type. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
34 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
35 In this section the first type is explained. Most items are also relevant for |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
36 writing filetype plugins. The specifics for filetype plugins are in the next |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
37 section |write-filetype-plugin|. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
38 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
39 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
40 NAME |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
41 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
42 First of all you must choose a name for your plugin. The features provided |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
43 by the plugin should be clear from its name. And it should be unlikely that |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
44 someone else writes a plugin with the same name but which does something |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
45 different. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
46 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
47 A script that corrects typing mistakes could be called "typecorrect.vim". We |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
48 will use it here as an example. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
49 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
50 For the plugin to work for everybody, it should follow a few guidelines. This |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
51 will be explained step-by-step. The complete example plugin is at the end. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
52 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
53 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
54 BODY |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
55 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
56 Let's start with the body of the plugin, the lines that do the actual work: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
57 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
58 14 iabbrev teh the |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
59 15 iabbrev otehr other |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
60 16 iabbrev wnat want |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
61 17 iabbrev synchronisation |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
62 18 \ synchronization |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
63 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
64 The actual list should be much longer, of course. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
65 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
66 The line numbers have only been added to explain a few things, don't put them |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
67 in your plugin file! |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
68 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
69 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
70 FIRST LINE |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
71 > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
72 1 vim9script noclear |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
73 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
74 You need to use `vimscript` as the very first command. Best is to put it in |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
75 the very first line. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
76 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
77 The script we are writing will have a `finish` command to bail out when it is |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
78 loaded a second time. To avoid that the items defined in the script are lost |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
79 the "noclear" argument is used. More info about this at |vim9-reload|. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
80 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
81 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
82 HEADER |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
83 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
84 You will probably add new corrections to the plugin and soon have several |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
85 versions lying around. And when distributing this file, people will want to |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
86 know who wrote this wonderful plugin and where they can send remarks. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
87 Therefore, put a header at the top of your plugin: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
88 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
89 2 # Vim global plugin for correcting typing mistakes |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
90 3 # Last Change: 2021 Dec 30 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
91 4 # Maintainer: Bram Moolenaar <Bram@vim.org> |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
92 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
93 About copyright and licensing: Since plugins are very useful and it's hardly |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
94 worth restricting their distribution, please consider making your plugin |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
95 either public domain or use the Vim |license|. A short note about this near |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
96 the top of the plugin should be sufficient. Example: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
97 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
98 5 # License: This file is placed in the public domain. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
99 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
100 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
101 LINE CONTINUATION AND AVOIDING SIDE EFFECTS *use-cpo-save* |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
102 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
103 In line 18 above, the line-continuation mechanism is used |line-continuation|. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
104 Users with 'compatible' set will run into trouble here, they will get an error |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
105 message. We can't just reset 'compatible', because that has a lot of side |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
106 effects. Instead, we will set the 'cpoptions' option to its Vim default |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
107 value and restore it later. That will allow the use of line-continuation and |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
108 make the script work for most people. It is done like this: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
109 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
110 11 var save_cpo = &cpo |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
111 12 set cpo&vim |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
112 .. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
113 42 &cpo = save_cpo |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
114 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
115 We first store the old value of 'cpoptions' in the "save_cpo" variable. At |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
116 the end of the plugin this value is restored. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
117 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
118 Notice that "save_cpo" is a script-local variable. A global variable could |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
119 already be in use for something else. Always use script-local variables for |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
120 things that are only used in the script. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
121 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
122 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
123 NOT LOADING |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
124 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
125 It is possible that a user doesn't always want to load this plugin. Or the |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
126 system administrator has dropped it in the system-wide plugin directory, but a |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
127 user has his own plugin he wants to use. Then the user must have a chance to |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
128 disable loading this specific plugin. These lines will make it possible: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
129 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
130 7 if exists("g:loaded_typecorrect") |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
131 8 finish |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
132 9 endif |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
133 10 g:loaded_typecorrect = 1 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
134 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
135 This also avoids that when the script is loaded twice it would pointlessly |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
136 redefine functions and cause trouble for autocommands that are added twice. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
137 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
138 The name is recommended to start with "g:loaded_" and then the file name of |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
139 the plugin, literally. The "g:" is prepended to make the variable global, so |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
140 that other places can check whether its functionality is available. Without |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
141 "g:" it would be local to the script. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
142 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
143 Using `finish` stops Vim from reading the rest of the file, it's much quicker |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
144 than using if-endif around the whole file, since Vim would still need to parse |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
145 the commands to find the `endif`. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
146 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
147 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
148 MAPPING |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
149 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
150 Now let's make the plugin more interesting: We will add a mapping that adds a |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
151 correction for the word under the cursor. We could just pick a key sequence |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
152 for this mapping, but the user might already use it for something else. To |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
153 allow the user to define which keys a mapping in a plugin uses, the <Leader> |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
154 item can be used: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
155 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
156 22 map <unique> <Leader>a <Plug>TypecorrAdd; |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
157 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
158 The "<Plug>TypecorrAdd;" thing will do the work, more about that further on. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
159 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
160 The user can set the "g:mapleader" variable to the key sequence that he wants |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
161 plugin mappings to start with. Thus if the user has done: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
162 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
163 g:mapleader = "_" |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
164 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
165 the mapping will define "_a". If the user didn't do this, the default value |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
166 will be used, which is a backslash. Then a map for "\a" will be defined. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
167 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
168 Note that <unique> is used, this will cause an error message if the mapping |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
169 already happened to exist. |:map-<unique>| |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
170 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
171 But what if the user wants to define his own key sequence? We can allow that |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
172 with this mechanism: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
173 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
174 21 if !hasmapto('<Plug>TypecorrAdd;') |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
175 22 map <unique> <Leader>a <Plug>TypecorrAdd; |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
176 23 endif |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
177 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
178 This checks if a mapping to "<Plug>TypecorrAdd;" already exists, and only |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
179 defines the mapping from "<Leader>a" if it doesn't. The user then has a |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
180 chance of putting this in his vimrc file: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
181 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
182 map ,c <Plug>TypecorrAdd; |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
183 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
184 Then the mapped key sequence will be ",c" instead of "_a" or "\a". |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
185 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
186 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
187 PIECES |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
188 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
189 If a script gets longer, you often want to break up the work in pieces. You |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
190 can use functions or mappings for this. But you don't want these functions |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
191 and mappings to interfere with the ones from other scripts. For example, you |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
192 could define a function Add(), but another script could try to define the same |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
193 function. To avoid this, we define the function local to the script. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
194 Fortunately, in |Vim9| script this is the default. In a legacy script you |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
195 would need to prefix the name with "s:". |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
196 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
197 We will define a function that adds a new typing correction: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
198 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
199 30 def Add(from: string, correct: bool) |
28933 | 200 31 var to = input($"type the correction for {from}: ") |
201 32 exe $":iabbrev {from} {to}" | |
28862
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
202 .. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
203 36 enddef |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
204 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
205 Now we can call the function Add() from within this script. If another |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
206 script also defines Add(), it will be local to that script and can only |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
207 be called from that script. There can also be a global g:Add() function, |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
208 which is again another function. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
209 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
210 <SID> can be used with mappings. It generates a script ID, which identifies |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
211 the current script. In our typing correction plugin we use it like this: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
212 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
213 24 noremap <unique> <script> <Plug>TypecorrAdd; <SID>Add |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
214 .. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
215 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), true)<CR> |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
216 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
217 Thus when a user types "\a", this sequence is invoked: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
218 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
219 \a -> <Plug>TypecorrAdd; -> <SID>Add -> :call <SID>Add(...) |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
220 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
221 If another script also maps <SID>Add, it will get another script ID and |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
222 thus define another mapping. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
223 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
224 Note that instead of Add() we use <SID>Add() here. That is because the |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
225 mapping is typed by the user, thus outside of the script context. The <SID> |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
226 is translated to the script ID, so that Vim knows in which script to look for |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
227 the Add() function. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
228 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
229 This is a bit complicated, but it's required for the plugin to work together |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
230 with other plugins. The basic rule is that you use <SID>Add() in mappings and |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
231 Add() in other places (the script itself, autocommands, user commands). |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
232 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
233 We can also add a menu entry to do the same as the mapping: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
234 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
235 26 noremenu <script> Plugin.Add\ Correction <SID>Add |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
236 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
237 The "Plugin" menu is recommended for adding menu items for plugins. In this |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
238 case only one item is used. When adding more items, creating a submenu is |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
239 recommended. For example, "Plugin.CVS" could be used for a plugin that offers |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
240 CVS operations "Plugin.CVS.checkin", "Plugin.CVS.checkout", etc. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
241 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
242 Note that in line 28 ":noremap" is used to avoid that any other mappings cause |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
243 trouble. Someone may have remapped ":call", for example. In line 24 we also |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
244 use ":noremap", but we do want "<SID>Add" to be remapped. This is why |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
245 "<script>" is used here. This only allows mappings which are local to the |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
246 script. |:map-<script>| The same is done in line 26 for ":noremenu". |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
247 |:menu-<script>| |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
248 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
249 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
250 <SID> AND <Plug> *using-<Plug>* |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
251 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
252 Both <SID> and <Plug> are used to avoid that mappings of typed keys interfere |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
253 with mappings that are only to be used from other mappings. Note the |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
254 difference between using <SID> and <Plug>: |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
255 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
256 <Plug> is visible outside of the script. It is used for mappings which the |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
257 user might want to map a key sequence to. <Plug> is a special code |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
258 that a typed key will never produce. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
259 To make it very unlikely that other plugins use the same sequence of |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
260 characters, use this structure: <Plug> scriptname mapname |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
261 In our example the scriptname is "Typecorr" and the mapname is "Add". |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
262 We add a semicolon as the terminator. This results in |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
263 "<Plug>TypecorrAdd;". Only the first character of scriptname and |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
264 mapname is uppercase, so that we can see where mapname starts. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
265 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
266 <SID> is the script ID, a unique identifier for a script. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
267 Internally Vim translates <SID> to "<SNR>123_", where "123" can be any |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
268 number. Thus a function "<SID>Add()" will have a name "<SNR>11_Add()" |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
269 in one script, and "<SNR>22_Add()" in another. You can see this if |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
270 you use the ":function" command to get a list of functions. The |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
271 translation of <SID> in mappings is exactly the same, that's how you |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
272 can call a script-local function from a mapping. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
273 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
274 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
275 USER COMMAND |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
276 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
277 Now let's add a user command to add a correction: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
278 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
279 38 if !exists(":Correct") |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
280 39 command -nargs=1 Correct :call Add(<q-args>, false) |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
281 40 endif |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
282 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
283 The user command is defined only if no command with the same name already |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
284 exists. Otherwise we would get an error here. Overriding the existing user |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
285 command with ":command!" is not a good idea, this would probably make the user |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
286 wonder why the command he defined himself doesn't work. |:command| |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
287 If it did happen you can find out who to blame with: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
288 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
289 verbose command Correct |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
290 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
291 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
292 SCRIPT VARIABLES |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
293 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
294 When a variable starts with "s:" it is a script variable. It can only be used |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
295 inside a script. Outside the script it's not visible. This avoids trouble |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
296 with using the same variable name in different scripts. The variables will be |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
297 kept as long as Vim is running. And the same variables are used when sourcing |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
298 the same script again. |s:var| |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
299 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
300 The nice thing about |Vim9| script is that variables are local to the script |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
301 by default. You can prepend "s:" if you like, but you do not need to. And |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
302 functions in the script can also use the script variables without a prefix. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
303 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
304 Script-local variables can also be used in functions, autocommands and user |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
305 commands that are defined in the script. Thus they are the perfect way to |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
306 share information between parts of your plugin, without it leaking out. In |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
307 our example we can add a few lines to count the number of corrections: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
308 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
309 19 var count = 4 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
310 .. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
311 30 def Add(from: string, correct: bool) |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
312 .. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
313 34 count += 1 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
314 35 echo "you now have " .. count .. " corrections" |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
315 36 enddef |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
316 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
317 "count" is declared and initialized to 4 in the script itself. When later |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
318 the Add() function is called, it increments "count". It doesn't matter from |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
319 where the function was called, since it has been defined in the script, it |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
320 will use the local variables from this script. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
321 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
322 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
323 THE RESULT |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
324 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
325 Here is the resulting complete example: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
326 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
327 1 vim9script noclear |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
328 2 # Vim global plugin for correcting typing mistakes |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
329 3 # Last Change: 2021 Dec 30 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
330 4 # Maintainer: Bram Moolenaar <Bram@vim.org> |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
331 5 # License: This file is placed in the public domain. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
332 6 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
333 7 if exists("g:loaded_typecorrect") |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
334 8 finish |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
335 9 endif |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
336 10 g:loaded_typecorrect = 1 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
337 11 var save_cpo = &cpo |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
338 12 set cpo&vim |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
339 13 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
340 14 iabbrev teh the |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
341 15 iabbrev otehr other |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
342 16 iabbrev wnat want |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
343 17 iabbrev synchronisation |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
344 18 \ synchronization |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
345 19 var count = 4 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
346 20 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
347 21 if !hasmapto('<Plug>TypecorrAdd;') |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
348 22 map <unique> <Leader>a <Plug>TypecorrAdd; |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
349 23 endif |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
350 24 noremap <unique> <script> <Plug>TypecorrAdd; <SID>Add |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
351 25 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
352 26 noremenu <script> Plugin.Add\ Correction <SID>Add |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
353 27 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
354 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), true)<CR> |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
355 29 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
356 30 def Add(from: string, correct: bool) |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
357 31 var to = input("type the correction for " .. from .. ": ") |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
358 32 exe ":iabbrev " .. from .. " " .. to |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
359 33 if correct | exe "normal viws\<C-R>\" \b\e" | endif |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
360 34 count += 1 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
361 35 echo "you now have " .. count .. " corrections" |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
362 36 enddef |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
363 37 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
364 38 if !exists(":Correct") |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
365 39 command -nargs=1 Correct call Add(<q-args>, false) |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
366 40 endif |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
367 41 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
368 42 &cpo = save_cpo |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
369 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
370 Line 33 wasn't explained yet. It applies the new correction to the word under |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
371 the cursor. The |:normal| command is used to use the new abbreviation. Note |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
372 that mappings and abbreviations are expanded here, even though the function |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
373 was called from a mapping defined with ":noremap". |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
374 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
375 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
376 DOCUMENTATION *write-local-help* |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
377 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
378 It's a good idea to also write some documentation for your plugin. Especially |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
379 when its behavior can be changed by the user. See |add-local-help| for how |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
380 they are installed. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
381 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
382 Here is a simple example for a plugin help file, called "typecorrect.txt": > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
383 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
384 1 *typecorrect.txt* Plugin for correcting typing mistakes |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
385 2 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
386 3 If you make typing mistakes, this plugin will have them corrected |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
387 4 automatically. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
388 5 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
389 6 There are currently only a few corrections. Add your own if you like. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
390 7 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
391 8 Mappings: |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
392 9 <Leader>a or <Plug>TypecorrAdd; |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
393 10 Add a correction for the word under the cursor. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
394 11 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
395 12 Commands: |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
396 13 :Correct {word} |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
397 14 Add a correction for {word}. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
398 15 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
399 16 *typecorrect-settings* |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
400 17 This plugin doesn't have any settings. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
401 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
402 The first line is actually the only one for which the format matters. It will |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
403 be extracted from the help file to be put in the "LOCAL ADDITIONS:" section of |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
404 help.txt |local-additions|. The first "*" must be in the first column of the |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
405 first line. After adding your help file do ":help" and check that the entries |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
406 line up nicely. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
407 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
408 You can add more tags inside ** in your help file. But be careful not to use |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
409 existing help tags. You would probably use the name of your plugin in most of |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
410 them, like "typecorrect-settings" in the example. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
411 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
412 Using references to other parts of the help in || is recommended. This makes |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
413 it easy for the user to find associated help. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
414 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
415 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
416 FILETYPE DETECTION *plugin-filetype* |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
417 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
418 If your filetype is not already detected by Vim, you should create a filetype |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
419 detection snippet in a separate file. It is usually in the form of an |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
420 autocommand that sets the filetype when the file name matches a pattern. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
421 Example: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
422 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
423 au BufNewFile,BufRead *.foo setlocal filetype=foofoo |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
424 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
425 Write this single-line file as "ftdetect/foofoo.vim" in the first directory |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
426 that appears in 'runtimepath'. For Unix that would be |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
427 "~/.vim/ftdetect/foofoo.vim". The convention is to use the name of the |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
428 filetype for the script name. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
429 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
430 You can make more complicated checks if you like, for example to inspect the |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
431 contents of the file to recognize the language. Also see |new-filetype|. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
432 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
433 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
434 SUMMARY *plugin-special* |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
435 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
436 Summary of special things to use in a plugin: |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
437 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
438 var name Variable local to the script. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
439 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
440 <SID> Script-ID, used for mappings and functions local to |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
441 the script. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
442 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
443 hasmapto() Function to test if the user already defined a mapping |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
444 for functionality the script offers. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
445 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
446 <Leader> Value of "mapleader", which the user defines as the |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
447 keys that plugin mappings start with. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
448 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
449 map <unique> Give a warning if a mapping already exists. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
450 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
451 noremap <script> Use only mappings local to the script, not global |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
452 mappings. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
453 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
454 exists(":Cmd") Check if a user command already exists. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
455 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
456 ============================================================================== |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
457 *51.2* Writing a filetype plugin *write-filetype-plugin* *ftplugin* |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
458 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
459 A filetype plugin is like a global plugin, except that it sets options and |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
460 defines mappings for the current buffer only. See |add-filetype-plugin| for |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
461 how this type of plugin is used. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
462 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
463 First read the section on global plugins above |51.1|. All that is said there |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
464 also applies to filetype plugins. There are a few extras, which are explained |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
465 here. The essential thing is that a filetype plugin should only have an |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
466 effect on the current buffer. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
467 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
468 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
469 DISABLING |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
470 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
471 If you are writing a filetype plugin to be used by many people, they need a |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
472 chance to disable loading it. Put this at the top of the plugin: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
473 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
474 # Only do this when not done yet for this buffer |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
475 if exists("b:did_ftplugin") |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
476 finish |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
477 endif |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
478 b:did_ftplugin = 1 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
479 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
480 This also needs to be used to avoid that the same plugin is executed twice for |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
481 the same buffer (happens when using an ":edit" command without arguments). |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
482 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
483 Now users can disable loading the default plugin completely by making a |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
484 filetype plugin with only these lines: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
485 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
486 vim9script |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
487 b:did_ftplugin = 1 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
488 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
489 This does require that the filetype plugin directory comes before $VIMRUNTIME |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
490 in 'runtimepath'! |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
491 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
492 If you do want to use the default plugin, but overrule one of the settings, |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
493 you can write the different setting in a script: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
494 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
495 setlocal textwidth=70 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
496 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
497 Now write this in the "after" directory, so that it gets sourced after the |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
498 distributed "vim.vim" ftplugin |after-directory|. For Unix this would be |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
499 "~/.vim/after/ftplugin/vim.vim". Note that the default plugin will have set |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
500 "b:did_ftplugin", but it is ignored here. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
501 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
502 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
503 OPTIONS |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
504 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
505 To make sure the filetype plugin only affects the current buffer use the > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
506 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
507 setlocal |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
508 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
509 command to set options. And only set options which are local to a buffer (see |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
510 the help for the option to check that). When using `:setlocal` for global |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
511 options or options local to a window, the value will change for many buffers, |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
512 and that is not what a filetype plugin should do. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
513 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
514 When an option has a value that is a list of flags or items, consider using |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
515 "+=" and "-=" to keep the existing value. Be aware that the user may have |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
516 changed an option value already. First resetting to the default value and |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
517 then changing it is often a good idea. Example: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
518 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
519 setlocal formatoptions& formatoptions+=ro |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
520 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
521 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
522 MAPPINGS |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
523 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
524 To make sure mappings will only work in the current buffer use the > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
525 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
526 map <buffer> |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
527 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
528 command. This needs to be combined with the two-step mapping explained above. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
529 An example of how to define functionality in a filetype plugin: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
530 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
531 if !hasmapto('<Plug>JavaImport;') |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
532 map <buffer> <unique> <LocalLeader>i <Plug>JavaImport; |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
533 endif |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
534 noremap <buffer> <unique> <Plug>JavaImport; oimport ""<Left><Esc> |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
535 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
536 |hasmapto()| is used to check if the user has already defined a map to |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
537 <Plug>JavaImport;. If not, then the filetype plugin defines the default |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
538 mapping. This starts with |<LocalLeader>|, which allows the user to select |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
539 the key(s) he wants filetype plugin mappings to start with. The default is a |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
540 backslash. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
541 "<unique>" is used to give an error message if the mapping already exists or |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
542 overlaps with an existing mapping. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
543 |:noremap| is used to avoid that any other mappings that the user has defined |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
544 interferes. You might want to use ":noremap <script>" to allow remapping |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
545 mappings defined in this script that start with <SID>. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
546 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
547 The user must have a chance to disable the mappings in a filetype plugin, |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
548 without disabling everything. Here is an example of how this is done for a |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
549 plugin for the mail filetype: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
550 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
551 # Add mappings, unless the user didn't want this. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
552 if !exists("g:no_plugin_maps") && !exists("g:no_mail_maps") |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
553 # Quote text by inserting "> " |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
554 if !hasmapto('<Plug>MailQuote;') |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
555 vmap <buffer> <LocalLeader>q <Plug>MailQuote; |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
556 nmap <buffer> <LocalLeader>q <Plug>MailQuote; |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
557 endif |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
558 vnoremap <buffer> <Plug>MailQuote; :s/^/> /<CR> |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
559 nnoremap <buffer> <Plug>MailQuote; :.,$s/^/> /<CR> |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
560 endif |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
561 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
562 Two global variables are used: |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
563 |g:no_plugin_maps| disables mappings for all filetype plugins |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
564 |g:no_mail_maps| disables mappings for the "mail" filetype |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
565 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
566 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
567 USER COMMANDS |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
568 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
569 To add a user command for a specific file type, so that it can only be used in |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
570 one buffer, use the "-buffer" argument to |:command|. Example: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
571 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
572 command -buffer Make make %:r.s |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
573 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
574 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
575 VARIABLES |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
576 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
577 A filetype plugin will be sourced for each buffer of the type it's for. Local |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
578 script variables will be shared between all invocations. Use local buffer |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
579 variables |b:var| if you want a variable specifically for one buffer. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
580 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
581 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
582 FUNCTIONS |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
583 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
584 When defining a function, this only needs to be done once. But the filetype |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
585 plugin will be sourced every time a file with this filetype will be opened. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
586 This construct makes sure the function is only defined once: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
587 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
588 if !exists("*Func") |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
589 def Func(arg) |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
590 ... |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
591 enddef |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
592 endif |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
593 < |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
594 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
595 UNDO *undo_indent* *undo_ftplugin* |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
596 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
597 When the user does ":setfiletype xyz" the effect of the previous filetype |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
598 should be undone. Set the b:undo_ftplugin variable to the commands that will |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
599 undo the settings in your filetype plugin. Example: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
600 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
601 let b:undo_ftplugin = "setlocal fo< com< tw< commentstring<" |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
602 \ .. "| unlet b:match_ignorecase b:match_words b:match_skip" |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
603 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
604 Using ":setlocal" with "<" after the option name resets the option to its |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
605 global value. That is mostly the best way to reset the option value. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
606 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
607 This does require removing the "C" flag from 'cpoptions' to allow line |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
608 continuation, as mentioned above |use-cpo-save|. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
609 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
610 For undoing the effect of an indent script, the b:undo_indent variable should |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
611 be set accordingly. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
612 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
613 Both these variables use legacy script syntax, not |Vim9| syntax. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
614 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
615 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
616 FILE NAME |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
617 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
618 The filetype must be included in the file name |ftplugin-name|. Use one of |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
619 these three forms: |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
620 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
621 .../ftplugin/stuff.vim |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
622 .../ftplugin/stuff_foo.vim |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
623 .../ftplugin/stuff/bar.vim |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
624 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
625 "stuff" is the filetype, "foo" and "bar" are arbitrary names. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
626 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
627 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
628 SUMMARY *ftplugin-special* |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
629 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
630 Summary of special things to use in a filetype plugin: |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
631 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
632 <LocalLeader> Value of "maplocalleader", which the user defines as |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
633 the keys that filetype plugin mappings start with. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
634 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
635 map <buffer> Define a mapping local to the buffer. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
636 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
637 noremap <script> Only remap mappings defined in this script that start |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
638 with <SID>. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
639 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
640 setlocal Set an option for the current buffer only. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
641 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
642 command -buffer Define a user command local to the buffer. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
643 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
644 exists("*s:Func") Check if a function was already defined. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
645 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
646 Also see |plugin-special|, the special things used for all plugins. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
647 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
648 ============================================================================== |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
649 *51.3* Writing a compiler plugin *write-compiler-plugin* |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
650 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
651 A compiler plugin sets options for use with a specific compiler. The user can |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
652 load it with the |:compiler| command. The main use is to set the |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
653 'errorformat' and 'makeprg' options. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
654 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
655 Easiest is to have a look at examples. This command will edit all the default |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
656 compiler plugins: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
657 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
658 next $VIMRUNTIME/compiler/*.vim |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
659 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
660 Type `:next` to go to the next plugin file. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
661 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
662 There are two special items about these files. First is a mechanism to allow |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
663 a user to overrule or add to the default file. The default files start with: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
664 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
665 vim9script |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
666 if exists("g:current_compiler") |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
667 finish |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
668 endif |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
669 g:current_compiler = "mine" |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
670 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
671 When you write a compiler file and put it in your personal runtime directory |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
672 (e.g., ~/.vim/compiler for Unix), you set the "current_compiler" variable to |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
673 make the default file skip the settings. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
674 *:CompilerSet* |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
675 The second mechanism is to use ":set" for ":compiler!" and ":setlocal" for |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
676 ":compiler". Vim defines the ":CompilerSet" user command for this. However, |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
677 older Vim versions don't, thus your plugin should define it then. This is an |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
678 example: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
679 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
680 if exists(":CompilerSet") != 2 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
681 command -nargs=* CompilerSet setlocal <args> |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
682 endif |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
683 CompilerSet errorformat& " use the default 'errorformat' |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
684 CompilerSet makeprg=nmake |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
685 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
686 When you write a compiler plugin for the Vim distribution or for a system-wide |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
687 runtime directory, use the mechanism mentioned above. When |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
688 "current_compiler" was already set by a user plugin nothing will be done. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
689 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
690 When you write a compiler plugin to overrule settings from a default plugin, |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
691 don't check "current_compiler". This plugin is supposed to be loaded |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
692 last, thus it should be in a directory at the end of 'runtimepath'. For Unix |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
693 that could be ~/.vim/after/compiler. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
694 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
695 ============================================================================== |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
696 *51.4* Writing a plugin that loads quickly *write-plugin-quickload* |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
697 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
698 A plugin may grow and become quite long. The startup delay may become |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
699 noticeable, while you hardly ever use the plugin. Then it's time for a |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
700 quickload plugin. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
701 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
702 The basic idea is that the plugin is loaded twice. The first time user |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
703 commands and mappings are defined that offer the functionality. The second |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
704 time the functions that implement the functionality are defined. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
705 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
706 It may sound surprising that quickload means loading a script twice. What we |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
707 mean is that it loads quickly the first time, postponing the bulk of the |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
708 script to the second time, which only happens when you actually use it. When |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
709 you always use the functionality it actually gets slower! |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
710 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
711 This uses a FuncUndefined autocommand. Since Vim 7 there is an alternative: |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
712 use the |autoload| functionality |51.5|. That will also use |Vim9| script |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
713 instead of legacy script that is used here. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
714 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
715 The following example shows how it's done: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
716 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
717 " Vim global plugin for demonstrating quick loading |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
718 " Last Change: 2005 Feb 25 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
719 " Maintainer: Bram Moolenaar <Bram@vim.org> |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
720 " License: This file is placed in the public domain. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
721 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
722 if !exists("s:did_load") |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
723 command -nargs=* BNRead call BufNetRead(<f-args>) |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
724 map <F19> :call BufNetWrite('something')<CR> |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
725 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
726 let s:did_load = 1 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
727 exe 'au FuncUndefined BufNet* source ' .. expand('<sfile>') |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
728 finish |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
729 endif |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
730 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
731 function BufNetRead(...) |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
732 echo 'BufNetRead(' .. string(a:000) .. ')' |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
733 " read functionality here |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
734 endfunction |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
735 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
736 function BufNetWrite(...) |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
737 echo 'BufNetWrite(' .. string(a:000) .. ')' |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
738 " write functionality here |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
739 endfunction |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
740 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
741 When the script is first loaded "s:did_load" is not set. The commands between |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
742 the "if" and "endif" will be executed. This ends in a |:finish| command, thus |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
743 the rest of the script is not executed. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
744 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
745 The second time the script is loaded "s:did_load" exists and the commands |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
746 after the "endif" are executed. This defines the (possible long) |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
747 BufNetRead() and BufNetWrite() functions. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
748 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
749 If you drop this script in your plugin directory Vim will execute it on |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
750 startup. This is the sequence of events that happens: |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
751 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
752 1. The "BNRead" command is defined and the <F19> key is mapped when the script |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
753 is sourced at startup. A |FuncUndefined| autocommand is defined. The |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
754 ":finish" command causes the script to terminate early. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
755 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
756 2. The user types the BNRead command or presses the <F19> key. The |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
757 BufNetRead() or BufNetWrite() function will be called. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
758 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
759 3. Vim can't find the function and triggers the |FuncUndefined| autocommand |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
760 event. Since the pattern "BufNet*" matches the invoked function, the |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
761 command "source fname" will be executed. "fname" will be equal to the name |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
762 of the script, no matter where it is located, because it comes from |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
763 expanding "<sfile>" (see |expand()|). |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
764 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
765 4. The script is sourced again, the "s:did_load" variable exists and the |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
766 functions are defined. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
767 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
768 Notice that the functions that are loaded afterwards match the pattern in the |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
769 |FuncUndefined| autocommand. You must make sure that no other plugin defines |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
770 functions that match this pattern. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
771 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
772 ============================================================================== |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
773 *51.5* Writing library scripts *write-library-script* |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
774 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
775 Some functionality will be required in several places. When this becomes more |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
776 than a few lines you will want to put it in one script and use it from many |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
777 scripts. We will call that one script a library script. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
778 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
779 Manually loading a library script is possible, so long as you avoid loading it |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
780 when it's already done. You can do this with the |exists()| function. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
781 Example: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
782 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
783 if !exists('*MyLibFunction') |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
784 runtime library/mylibscript.vim |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
785 endif |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
786 MyLibFunction(arg) |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
787 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
788 Here you need to know that MyLibFunction() is defined in a script |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
789 "library/mylibscript.vim" in one of the directories in 'runtimepath'. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
790 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
791 To make this a bit simpler Vim offers the autoload mechanism. Then the |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
792 example looks like this: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
793 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
794 mylib#myfunction(arg) |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
795 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
796 That's a lot simpler, isn't it? Vim will recognize the function name by the |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
797 embedded "#" character and when it's not defined search for the script |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
798 "autoload/mylib.vim" in 'runtimepath'. That script must define the |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
799 "mylib#myfunction()" function. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
800 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
801 You can put many other functions in the mylib.vim script, you are free to |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
802 organize your functions in library scripts. But you must use function names |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
803 where the part before the '#' matches the script name. Otherwise Vim would |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
804 not know what script to load. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
805 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
806 If you get really enthusiastic and write lots of library scripts, you may |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
807 want to use subdirectories. Example: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
808 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
809 netlib#ftp#read('somefile') |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
810 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
811 For Unix the library script used for this could be: |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
812 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
813 ~/.vim/autoload/netlib/ftp.vim |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
814 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
815 Where the function is defined like this: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
816 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
817 def netlib#ftp#read(fname: string) |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
818 # Read the file fname through ftp |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
819 enddef |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
820 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
821 Notice that the name the function is defined with is exactly the same as the |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
822 name used for calling the function. And the part before the last '#' |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
823 exactly matches the subdirectory and script name. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
824 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
825 You can use the same mechanism for variables: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
826 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
827 var weekdays = dutch#weekdays |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
828 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
829 This will load the script "autoload/dutch.vim", which should contain something |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
830 like: > |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
831 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
832 var dutch#weekdays = ['zondag', 'maandag', 'dinsdag', 'woensdag', |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
833 \ 'donderdag', 'vrijdag', 'zaterdag'] |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
834 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
835 Further reading: |autoload|. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
836 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
837 ============================================================================== |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
838 *51.6* Distributing Vim scripts *distribute-script* |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
839 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
840 Vim users will look for scripts on the Vim website: http://www.vim.org. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
841 If you made something that is useful for others, share it! |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
842 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
843 Another place is github. But there you need to know where to find it! The |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
844 advantage is that most plugin managers fetch plugins from github. You'll have |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
845 to use your favorite search engine to find them. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
846 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
847 Vim scripts can be used on any system. However, there might not be a tar or |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
848 gzip command. If you want to pack files together and/or compress them the |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
849 "zip" utility is recommended. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
850 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
851 For utmost portability use Vim itself to pack scripts together. This can be |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
852 done with the Vimball utility. See |vimball|. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
853 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
854 It's good if you add a line to allow automatic updating. See |glvs-plugins|. |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
855 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
856 ============================================================================== |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
857 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
858 Next chapter: |usr_52.txt| Write plugins using Vim9 script |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
859 |
82244cfc4694
Update runtime files, new color schemes
Bram Moolenaar <Bram@vim.org>
parents:
diff
changeset
|
860 Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: |