Update runtime files
diff --git a/runtime/doc/usr_51.txt b/runtime/doc/usr_51.txt
index 2845ab8..73733f4 100644
--- a/runtime/doc/usr_51.txt
+++ b/runtime/doc/usr_51.txt
@@ -1,4 +1,4 @@
-*usr_51.txt* For Vim version 8.2. Last change: 2022 May 14
+*usr_51.txt* For Vim version 8.2. Last change: 2022 Jun 03
VIM USER MANUAL - by Bram Moolenaar
@@ -12,11 +12,9 @@
|51.1| Writing a generic plugin
|51.2| Writing a filetype plugin
|51.3| Writing a compiler plugin
-|51.4| Writing a plugin that loads quickly
-|51.5| Writing library scripts
-|51.6| Distributing Vim scripts
+|51.4| Distributing Vim scripts
- Next chapter: |usr_52.txt| Write plugins using Vim9 script
+ Next chapter: |usr_52.txt| Write large plugins
Previous chapter: |usr_50.txt| Advanced Vim script writing
Table of contents: |usr_toc.txt|
@@ -36,6 +34,9 @@
writing filetype plugins. The specifics for filetype plugins are in the next
section |write-filetype-plugin|.
+We will use |Vim9| syntax here, the recommended way to write new plugins.
+Make sure the file starts with the `vim9script` command.
+
NAME
@@ -55,11 +56,11 @@
Let's start with the body of the plugin, the lines that do the actual work: >
- 14 iabbrev teh the
- 15 iabbrev otehr other
- 16 iabbrev wnat want
- 17 iabbrev synchronisation
- 18 \ synchronization
+ 12 iabbrev teh the
+ 13 iabbrev otehr other
+ 14 iabbrev wnat want
+ 15 iabbrev synchronisation
+ 16 \ synchronization
The actual list should be much longer, of course.
@@ -98,28 +99,6 @@
5 # License: This file is placed in the public domain.
-LINE CONTINUATION AND AVOIDING SIDE EFFECTS *use-cpo-save*
-
-In line 18 above, the line-continuation mechanism is used |line-continuation|.
-Users with 'compatible' set will run into trouble here, they will get an error
-message. We can't just reset 'compatible', because that has a lot of side
-effects. Instead, we will set the 'cpoptions' option to its Vim default
-value and restore it later. That will allow the use of line-continuation and
-make the script work for most people. It is done like this: >
-
- 11 var save_cpo = &cpo
- 12 set cpo&vim
- ..
- 42 &cpo = save_cpo
-
-We first store the old value of 'cpoptions' in the "save_cpo" variable. At
-the end of the plugin this value is restored.
-
-Notice that "save_cpo" is a script-local variable. A global variable could
-already be in use for something else. Always use script-local variables for
-things that are only used in the script.
-
-
NOT LOADING
It is possible that a user doesn't always want to load this plugin. Or the
@@ -153,7 +132,7 @@
allow the user to define which keys a mapping in a plugin uses, the <Leader>
item can be used: >
- 22 map <unique> <Leader>a <Plug>TypecorrAdd;
+ 20 map <unique> <Leader>a <Plug>TypecorrAdd;
The "<Plug>TypecorrAdd;" thing will do the work, more about that further on.
@@ -171,9 +150,9 @@
But what if the user wants to define his own key sequence? We can allow that
with this mechanism: >
- 21 if !hasmapto('<Plug>TypecorrAdd;')
- 22 map <unique> <Leader>a <Plug>TypecorrAdd;
- 23 endif
+ 19 if !hasmapto('<Plug>TypecorrAdd;')
+ 20 map <unique> <Leader>a <Plug>TypecorrAdd;
+ 21 endif
This checks if a mapping to "<Plug>TypecorrAdd;" already exists, and only
defines the mapping from "<Leader>a" if it doesn't. The user then has a
@@ -196,11 +175,11 @@
We will define a function that adds a new typing correction: >
- 30 def Add(from: string, correct: bool)
- 31 var to = input($"type the correction for {from}: ")
- 32 exe $":iabbrev {from} {to}"
- ..
- 36 enddef
+ 28 def Add(from: string, correct: bool)
+ 29 var to = input($"type the correction for {from}: ")
+ 30 exe $":iabbrev {from} {to}"
+ ...
+ 34 enddef
Now we can call the function Add() from within this script. If another
script also defines Add(), it will be local to that script and can only
@@ -210,9 +189,9 @@
<SID> can be used with mappings. It generates a script ID, which identifies
the current script. In our typing correction plugin we use it like this: >
- 24 noremap <unique> <script> <Plug>TypecorrAdd; <SID>Add
- ..
- 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), true)<CR>
+ 22 noremap <unique> <script> <Plug>TypecorrAdd; <SID>Add
+ ...
+ 26 noremap <SID>Add :call <SID>Add(expand("<cword>"), true)<CR>
Thus when a user types "\a", this sequence is invoked: >
@@ -232,7 +211,7 @@
We can also add a menu entry to do the same as the mapping: >
- 26 noremenu <script> Plugin.Add\ Correction <SID>Add
+ 24 noremenu <script> Plugin.Add\ Correction <SID>Add
The "Plugin" menu is recommended for adding menu items for plugins. In this
case only one item is used. When adding more items, creating a submenu is
@@ -276,9 +255,9 @@
Now let's add a user command to add a correction: >
- 38 if !exists(":Correct")
- 39 command -nargs=1 Correct :call Add(<q-args>, false)
- 40 endif
+ 36 if !exists(":Correct")
+ 37 command -nargs=1 Correct :call Add(<q-args>, false)
+ 38 endif
The user command is defined only if no command with the same name already
exists. Otherwise we would get an error here. Overriding the existing user
@@ -299,20 +278,21 @@
The nice thing about |Vim9| script is that variables are local to the script
by default. You can prepend "s:" if you like, but you do not need to. And
-functions in the script can also use the script variables without a prefix.
+functions in the script can also use the script variables without a prefix
+(they must be declared before the function for this to work).
Script-local variables can also be used in functions, autocommands and user
commands that are defined in the script. Thus they are the perfect way to
share information between parts of your plugin, without it leaking out. In
our example we can add a few lines to count the number of corrections: >
- 19 var count = 4
- ..
- 30 def Add(from: string, correct: bool)
- ..
- 34 count += 1
- 35 echo "you now have " .. count .. " corrections"
- 36 enddef
+ 17 var count = 4
+ ...
+ 28 def Add(from: string, correct: bool)
+ ...
+ 32 count += 1
+ 33 echo "you now have " .. count .. " corrections"
+ 34 enddef
"count" is declared and initialized to 4 in the script itself. When later
the Add() function is called, it increments "count". It doesn't matter from
@@ -334,40 +314,36 @@
8 finish
9 endif
10 g:loaded_typecorrect = 1
- 11 var save_cpo = &cpo
- 12 set cpo&vim
- 13
- 14 iabbrev teh the
- 15 iabbrev otehr other
- 16 iabbrev wnat want
- 17 iabbrev synchronisation
- 18 \ synchronization
- 19 var count = 4
- 20
- 21 if !hasmapto('<Plug>TypecorrAdd;')
- 22 map <unique> <Leader>a <Plug>TypecorrAdd;
- 23 endif
- 24 noremap <unique> <script> <Plug>TypecorrAdd; <SID>Add
+ 11
+ 12 iabbrev teh the
+ 13 iabbrev otehr other
+ 14 iabbrev wnat want
+ 15 iabbrev synchronisation
+ 16 \ synchronization
+ 17 var count = 4
+ 18
+ 19 if !hasmapto('<Plug>TypecorrAdd;')
+ 20 map <unique> <Leader>a <Plug>TypecorrAdd;
+ 21 endif
+ 22 noremap <unique> <script> <Plug>TypecorrAdd; <SID>Add
+ 23
+ 24 noremenu <script> Plugin.Add\ Correction <SID>Add
25
- 26 noremenu <script> Plugin.Add\ Correction <SID>Add
+ 26 noremap <SID>Add :call <SID>Add(expand("<cword>"), true)<CR>
27
- 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), true)<CR>
- 29
- 30 def Add(from: string, correct: bool)
- 31 var to = input("type the correction for " .. from .. ": ")
- 32 exe ":iabbrev " .. from .. " " .. to
- 33 if correct | exe "normal viws\<C-R>\" \b\e" | endif
- 34 count += 1
- 35 echo "you now have " .. count .. " corrections"
- 36 enddef
- 37
- 38 if !exists(":Correct")
- 39 command -nargs=1 Correct call Add(<q-args>, false)
- 40 endif
- 41
- 42 &cpo = save_cpo
+ 28 def Add(from: string, correct: bool)
+ 29 var to = input("type the correction for " .. from .. ": ")
+ 30 exe ":iabbrev " .. from .. " " .. to
+ 31 if correct | exe "normal viws\<C-R>\" \b\e" | endif
+ 32 count += 1
+ 33 echo "you now have " .. count .. " corrections"
+ 34 enddef
+ 35
+ 36 if !exists(":Correct")
+ 37 command -nargs=1 Correct call Add(<q-args>, false)
+ 38 endif
-Line 33 wasn't explained yet. It applies the new correction to the word under
+Line 31 wasn't explained yet. It applies the new correction to the word under
the cursor. The |:normal| command is used to use the new abbreviation. Note
that mappings and abbreviations are expanded here, even though the function
was called from a mapping defined with ":noremap".
@@ -413,24 +389,6 @@
it easy for the user to find associated help.
-FILETYPE DETECTION *plugin-filetype*
-
-If your filetype is not already detected by Vim, you should create a filetype
-detection snippet in a separate file. It is usually in the form of an
-autocommand that sets the filetype when the file name matches a pattern.
-Example: >
-
- au BufNewFile,BufRead *.foo setlocal filetype=foofoo
-
-Write this single-line file as "ftdetect/foofoo.vim" in the first directory
-that appears in 'runtimepath'. For Unix that would be
-"~/.vim/ftdetect/foofoo.vim". The convention is to use the name of the
-filetype for the script name.
-
-You can make more complicated checks if you like, for example to inspect the
-contents of the file to recognize the language. Also see |new-filetype|.
-
-
SUMMARY *plugin-special*
Summary of special things to use in a plugin:
@@ -497,7 +455,7 @@
Now write this in the "after" directory, so that it gets sourced after the
distributed "vim.vim" ftplugin |after-directory|. For Unix this would be
"~/.vim/after/ftplugin/vim.vim". Note that the default plugin will have set
-"b:did_ftplugin", but it is ignored here.
+"b:did_ftplugin", it is ignored here.
OPTIONS
@@ -591,6 +549,9 @@
enddef
endif
<
+Don't forget to use "noclear" with the `vim9script` command to avoid that the
+function is deleted when the script is sourced a second time.
+
UNDO *undo_indent* *undo_ftplugin*
@@ -598,15 +559,12 @@
should be undone. Set the b:undo_ftplugin variable to the commands that will
undo the settings in your filetype plugin. Example: >
- let b:undo_ftplugin = "setlocal fo< com< tw< commentstring<"
+ b:undo_ftplugin = "setlocal fo< com< tw< commentstring<"
\ .. "| unlet b:match_ignorecase b:match_words b:match_skip"
Using ":setlocal" with "<" after the option name resets the option to its
global value. That is mostly the best way to reset the option value.
-This does require removing the "C" flag from 'cpoptions' to allow line
-continuation, as mentioned above |use-cpo-save|.
-
For undoing the effect of an indent script, the b:undo_indent variable should
be set accordingly.
@@ -625,6 +583,24 @@
"stuff" is the filetype, "foo" and "bar" are arbitrary names.
+FILETYPE DETECTION *plugin-filetype*
+
+If your filetype is not already detected by Vim, you should create a filetype
+detection snippet in a separate file. It is usually in the form of an
+autocommand that sets the filetype when the file name matches a pattern.
+Example: >
+
+ au BufNewFile,BufRead *.foo setlocal filetype=foofoo
+
+Write this single-line file as "ftdetect/foofoo.vim" in the first directory
+that appears in 'runtimepath'. For Unix that would be
+"~/.vim/ftdetect/foofoo.vim". The convention is to use the name of the
+filetype for the script name.
+
+You can make more complicated checks if you like, for example to inspect the
+contents of the file to recognize the language. Also see |new-filetype|.
+
+
SUMMARY *ftplugin-special*
Summary of special things to use in a filetype plugin:
@@ -693,149 +669,7 @@
that could be ~/.vim/after/compiler.
==============================================================================
-*51.4* Writing a plugin that loads quickly *write-plugin-quickload*
-
-A plugin may grow and become quite long. The startup delay may become
-noticeable, while you hardly ever use the plugin. Then it's time for a
-quickload plugin.
-
-The basic idea is that the plugin is loaded twice. The first time user
-commands and mappings are defined that offer the functionality. The second
-time the functions that implement the functionality are defined.
-
-It may sound surprising that quickload means loading a script twice. What we
-mean is that it loads quickly the first time, postponing the bulk of the
-script to the second time, which only happens when you actually use it. When
-you always use the functionality it actually gets slower!
-
-This uses a FuncUndefined autocommand. Since Vim 7 there is an alternative:
-use the |autoload| functionality |51.5|. That will also use |Vim9| script
-instead of legacy script that is used here.
-
-The following example shows how it's done: >
-
- " Vim global plugin for demonstrating quick loading
- " Last Change: 2005 Feb 25
- " Maintainer: Bram Moolenaar <Bram@vim.org>
- " License: This file is placed in the public domain.
-
- if !exists("s:did_load")
- command -nargs=* BNRead call BufNetRead(<f-args>)
- map <F19> :call BufNetWrite('something')<CR>
-
- let s:did_load = 1
- exe 'au FuncUndefined BufNet* source ' .. expand('<sfile>')
- finish
- endif
-
- function BufNetRead(...)
- echo 'BufNetRead(' .. string(a:000) .. ')'
- " read functionality here
- endfunction
-
- function BufNetWrite(...)
- echo 'BufNetWrite(' .. string(a:000) .. ')'
- " write functionality here
- endfunction
-
-When the script is first loaded "s:did_load" is not set. The commands between
-the "if" and "endif" will be executed. This ends in a |:finish| command, thus
-the rest of the script is not executed.
-
-The second time the script is loaded "s:did_load" exists and the commands
-after the "endif" are executed. This defines the (possible long)
-BufNetRead() and BufNetWrite() functions.
-
-If you drop this script in your plugin directory Vim will execute it on
-startup. This is the sequence of events that happens:
-
-1. The "BNRead" command is defined and the <F19> key is mapped when the script
- is sourced at startup. A |FuncUndefined| autocommand is defined. The
- ":finish" command causes the script to terminate early.
-
-2. The user types the BNRead command or presses the <F19> key. The
- BufNetRead() or BufNetWrite() function will be called.
-
-3. Vim can't find the function and triggers the |FuncUndefined| autocommand
- event. Since the pattern "BufNet*" matches the invoked function, the
- command "source fname" will be executed. "fname" will be equal to the name
- of the script, no matter where it is located, because it comes from
- expanding "<sfile>" (see |expand()|).
-
-4. The script is sourced again, the "s:did_load" variable exists and the
- functions are defined.
-
-Notice that the functions that are loaded afterwards match the pattern in the
-|FuncUndefined| autocommand. You must make sure that no other plugin defines
-functions that match this pattern.
-
-==============================================================================
-*51.5* Writing library scripts *write-library-script*
-
-Some functionality will be required in several places. When this becomes more
-than a few lines you will want to put it in one script and use it from many
-scripts. We will call that one script a library script.
-
-Manually loading a library script is possible, so long as you avoid loading it
-when it's already done. You can do this with the |exists()| function.
-Example: >
-
- if !exists('*MyLibFunction')
- runtime library/mylibscript.vim
- endif
- MyLibFunction(arg)
-
-Here you need to know that MyLibFunction() is defined in a script
-"library/mylibscript.vim" in one of the directories in 'runtimepath'.
-
-To make this a bit simpler Vim offers the autoload mechanism. Then the
-example looks like this: >
-
- mylib#myfunction(arg)
-
-That's a lot simpler, isn't it? Vim will recognize the function name by the
-embedded "#" character and when it's not defined search for the script
-"autoload/mylib.vim" in 'runtimepath'. That script must define the
-"mylib#myfunction()" function.
-
-You can put many other functions in the mylib.vim script, you are free to
-organize your functions in library scripts. But you must use function names
-where the part before the '#' matches the script name. Otherwise Vim would
-not know what script to load.
-
-If you get really enthusiastic and write lots of library scripts, you may
-want to use subdirectories. Example: >
-
- netlib#ftp#read('somefile')
-
-For Unix the library script used for this could be:
-
- ~/.vim/autoload/netlib/ftp.vim
-
-Where the function is defined like this: >
-
- def netlib#ftp#read(fname: string)
- # Read the file fname through ftp
- enddef
-
-Notice that the name the function is defined with is exactly the same as the
-name used for calling the function. And the part before the last '#'
-exactly matches the subdirectory and script name.
-
-You can use the same mechanism for variables: >
-
- var weekdays = dutch#weekdays
-
-This will load the script "autoload/dutch.vim", which should contain something
-like: >
-
- var dutch#weekdays = ['zondag', 'maandag', 'dinsdag', 'woensdag',
- \ 'donderdag', 'vrijdag', 'zaterdag']
-
-Further reading: |autoload|.
-
-==============================================================================
-*51.6* Distributing Vim scripts *distribute-script*
+*51.4* Distributing Vim scripts *distribute-script*
Vim users will look for scripts on the Vim website: http://www.vim.org.
If you made something that is useful for others, share it!
@@ -855,6 +689,6 @@
==============================================================================
-Next chapter: |usr_52.txt| Write plugins using Vim9 script
+Next chapter: |usr_52.txt| Write large plugins
Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: