Mercurial > vim
annotate runtime/doc/usr_40.txt @ 32936:c517845bd10e v9.0.1776
patch 9.0.1776: No support for stable Python 3 ABI
Commit: https://github.com/vim/vim/commit/c13b3d1350b60b94fe87f0761ea31c0e7fb6ebf3
Author: Yee Cheng Chin <ychin.git@gmail.com>
Date: Sun Aug 20 21:18:38 2023 +0200
patch 9.0.1776: No support for stable Python 3 ABI
Problem: No support for stable Python 3 ABI
Solution: Support Python 3 stable ABI
Commits:
1) Support Python 3 stable ABI to allow mixed version interoperatbility
Vim currently supports embedding Python for use with plugins, and the
"dynamic" linking option allows the user to specify a locally installed
version of Python by setting `pythonthreedll`. However, one caveat is
that the Python 3 libs are not binary compatible across minor versions,
and mixing versions can potentially be dangerous (e.g. let's say Vim was
linked against the Python 3.10 SDK, but the user sets `pythonthreedll`
to a 3.11 lib). Usually, nothing bad happens, but in theory this could
lead to crashes, memory corruption, and other unpredictable behaviors.
It's also difficult for the user to tell something is wrong because Vim
has no way of reporting what Python 3 version Vim was linked with.
For Vim installed via a package manager, this usually isn't an issue
because all the dependencies would already be figured out. For prebuilt
Vim binaries like MacVim (my motivation for working on this), AppImage,
and Win32 installer this could potentially be an issue as usually a
single binary is distributed. This is more tricky when a new Python
version is released, as there's a chicken-and-egg issue with deciding
what Python version to build against and hard to keep in sync when a new
Python version just drops and we have a mix of users of different Python
versions, and a user just blindly upgrading to a new Python could lead to
bad interactions with Vim.
Python 3 does have a solution for this problem: stable ABI / limited API
(see https://docs.python.org/3/c-api/stable.html). The C SDK limits the
API to a set of functions that are promised to be stable across
versions. This pull request adds an ifdef config that allows us to turn
it on when building Vim. Vim binaries built with this option should be
safe to freely link with any Python 3 libraies without having the
constraint of having to use the same minor version.
Note: Python 2 has no such concept and this doesn't change how Python 2
integration works (not that there is going to be a new version of Python
2 that would cause compatibility issues in the future anyway).
---
Technical details:
======
The stable ABI can be accessed when we compile with the Python 3 limited
API (by defining `Py_LIMITED_API`). The Python 3 code (in `if_python3.c`
and `if_py_both.h`) would now handle this and switch to limited API
mode. Without it set, Vim will still use the full API as before so this
is an opt-in change.
The main difference is that `PyType_Object` is now an opaque struct that
we can't directly create "static types" out of, and we have to create
type objects as "heap types" instead. This is because the struct is not
stable and changes from version to version (e.g. 3.8 added a
`tp_vectorcall` field to it). I had to change all the types to be
allocated on the heap instead with just a pointer to them.
Other functions are also simply missing in limited API, or they are
introduced too late (e.g. `PyUnicode_AsUTF8AndSize` in 3.10) to it that
we need some other ways to do the same thing, so I had to abstract a few
things into macros, and sometimes re-implement functions like
`PyObject_NEW`.
One caveat is that in limited API, `OutputType` (used for replacing
`sys.stdout`) no longer inherits from `PyStdPrinter_Type` which I don't
think has any real issue other than minor differences in how they
convert to a string and missing a couple functions like `mode()` and
`fileno()`.
Also fixed an existing bug where `tp_basicsize` was set incorrectly for
`BufferObject`, `TabListObject, `WinListObject`.
Technically, there could be a small performance drop, there is a little
more indirection with accessing type objects, and some APIs like
`PyUnicode_AsUTF8AndSize` are missing, but in practice I didn't see any
difference, and any well-written Python plugin should try to avoid
excessing callbacks to the `vim` module in Python anyway.
I only tested limited API mode down to Python 3.7, which seemes to
compile and work fine. I haven't tried earlier Python versions.
2) Fix PyIter_Check on older Python vers / type##Ptr unused warning
For PyIter_Check, older versions exposed them as either macros (used in
full API), or a function (for use in limited API). A previous change
exposed PyIter_Check to the dynamic build because Python just moved it
to function-only in 3.10 anyway. Because of that, just make sure we
always grab the function in dynamic builds in earlier versions since
that's what Python eventually did anyway.
3) Move Py_LIMITED_API define to configure script
Can now use --with-python-stable-abi flag to customize what stable ABI
version to target. Can also use an env var to do so as well.
4) Show +python/dyn-stable in :version, and allow has() feature query
Not sure if the "/dyn-stable" suffix would break things, or whether we
should do it another way. Or just don't show it in version and rely on
has() feature checking.
5) Documentation first draft. Still need to implement v:python3_version
6) Fix PyIter_Check build breaks when compiling against Python 3.8
7) Add CI coverage stable ABI on Linux/Windows / make configurable on Windows
This adds configurable options for Windows make files (both MinGW and
MSVC). CI will also now exercise both traditional full API and stable
ABI for Linux and Windows in the matrix for coverage.
Also added a "dynamic" option to Linux matrix as a drive-by change to
make other scripting languages like Ruby / Perl testable under both
static and dynamic builds.
8) Fix inaccuracy in Windows docs
Python's own docs are confusing but you don't actually want to use
`python3.dll` for the dynamic linkage.
9) Add generated autoconf file
10) Add v:python3_version support
This variable indicates the version of Python3 that Vim was built
against (PY_VERSION_HEX), and will be useful to check whether the Python
library you are loading in dynamically actually fits it. When built with
stable ABI, it will be the limited ABI version instead
(`Py_LIMITED_API`), which indicates the minimum version of Python 3 the
user should have, rather than the exact match. When stable ABI is used,
we won't be exposing PY_VERSION_HEX in this var because it just doesn't
seem necessary to do so (the whole point of stable ABI is the promise
that it will work across versions), and I don't want to confuse the user
with too many variables.
Also, cleaned up some documentation, and added help tags.
11) Fix Python 3.7 compat issues
Fix a couple issues when using limited API < 3.8
- Crash on exit: In Python 3.7, if a heap-allocated type is destroyed
before all instances are, it would cause a crash later. This happens
when we destroyed `OptionsType` before calling `Py_Finalize` when
using the limited API. To make it worse, later versions changed the
semantics and now each instance has a strong reference to its own type
and the recommendation has changed to have each instance de-ref its
own type and have its type in GC traversal. To avoid dealing with
these cross-version variations, we just don't free the heap type. They
are static types in non-limited-API anyway and are designed to last
through the entirety of the app, and we also don't restart the Python
runtime and therefore do not need it to have absolutely 0 leaks.
See:
- https://docs.python.org/3/whatsnew/3.8.html#changes-in-the-c-api
- https://docs.python.org/3/whatsnew/3.9.html#changes-in-the-c-api
- PyIter_Check: This function is not provided in limited APIs older than
3.8. Previously I was trying to mock it out using manual
PyType_GetSlot() but it was brittle and also does not actually work
properly for static types (it will generate a Python error). Just
return false. It does mean using limited API < 3.8 is not recommended
as you lose the functionality to handle iterators, but from playing
with plugins I couldn't find it to be an issue.
- Fix loading of PyIter_Check so it will be done when limited API < 3.8.
Otherwise loading a 3.7 Python lib will fail even if limited API was
specified to use it.
12) Make sure to only load `PyUnicode_AsUTF8AndSize` in needed in limited API
We don't use this function unless limited API >= 3.10, but we were
loading it regardless. Usually it's ok in Unix-like systems where Python
just has a single lib that we load from, but in Windows where there is a
separate python3.dll this would not work as the symbol would not have
been exposed in this more limited DLL file. This makes it much clearer
under what condition is this function needed.
closes: #12032
Signed-off-by: Christian Brabandt <cb@256bit.org>
Co-authored-by: Yee Cheng Chin <ychin.git@gmail.com>
| author | Christian Brabandt <cb@256bit.org> |
|---|---|
| date | Sun, 20 Aug 2023 21:30:04 +0200 |
| parents | f8116058ca76 |
| children | 4635e43f2c6f |
| rev | line source |
|---|---|
| 29314 | 1 *usr_40.txt* For Vim version 9.0. Last change: 2022 Jun 23 |
| 7 | 2 |
| 3 VIM USER MANUAL - by Bram Moolenaar | |
| 4 | |
| 5 Make new commands | |
| 6 | |
| 7 | |
| 8 Vim is an extensible editor. You can take a sequence of commands you use | |
| 9 often and turn it into a new command. Or redefine an existing command. | |
| 10 Autocommands make it possible to execute commands automatically. | |
| 11 | |
| 12 |40.1| Key mapping | |
| 13 |40.2| Defining command-line commands | |
| 14 |40.3| Autocommands | |
| 15 | |
| 16 Next chapter: |usr_41.txt| Write a Vim script | |
| 800 | 17 Previous chapter: |usr_32.txt| The undo tree |
| 7 | 18 Table of contents: |usr_toc.txt| |
| 19 | |
| 20 ============================================================================== | |
| 21 *40.1* Key mapping | |
| 22 | |
| 27036 | 23 A simple mapping was explained in section |05.4|. The principle is that one |
| 7 | 24 sequence of key strokes is translated into another sequence of key strokes. |
| 25 This is a simple, yet powerful mechanism. | |
| 26 The simplest form is that one key is mapped to a sequence of keys. Since | |
|
2207
b17bbfa96fa0
Add the settabvar() and gettabvar() functions.
Bram Moolenaar <bram@vim.org>
parents:
2154
diff
changeset
|
27 the function keys, except <F1>, have no predefined meaning in Vim, these are |
|
b17bbfa96fa0
Add the settabvar() and gettabvar() functions.
Bram Moolenaar <bram@vim.org>
parents:
2154
diff
changeset
|
28 good choices to map. Example: > |
| 7 | 29 |
| 30 :map <F2> GoDate: <Esc>:read !date<CR>kJ | |
| 31 | |
| 32 This shows how three modes are used. After going to the last line with "G", | |
| 33 the "o" command opens a new line and starts Insert mode. The text "Date: " is | |
| 34 inserted and <Esc> takes you out of insert mode. | |
| 35 Notice the use of special keys inside <>. This is called angle bracket | |
| 36 notation. You type these as separate characters, not by pressing the key | |
| 37 itself. This makes the mappings better readable and you can copy and paste | |
| 38 the text without problems. | |
| 39 The ":" character takes Vim to the command line. The ":read !date" command | |
| 40 reads the output from the "date" command and appends it below the current | |
| 41 line. The <CR> is required to execute the ":read" command. | |
| 42 At this point of execution the text looks like this: | |
| 43 | |
| 44 Date: ~ | |
| 45 Fri Jun 15 12:54:34 CEST 2001 ~ | |
| 46 | |
| 47 Now "kJ" moves the cursor up and joins the lines together. | |
| 48 To decide which key or keys you use for mapping, see |map-which-keys|. | |
| 49 | |
| 50 | |
| 51 MAPPING AND MODES | |
| 52 | |
| 53 The ":map" command defines remapping for keys in Normal mode. You can also | |
| 54 define mappings for other modes. For example, ":imap" applies to Insert mode. | |
| 55 You can use it to insert a date below the cursor: > | |
| 56 | |
| 57 :imap <F2> <CR>Date: <Esc>:read !date<CR>kJ | |
| 58 | |
| 59 It looks a lot like the mapping for <F2> in Normal mode, only the start is | |
| 60 different. The <F2> mapping for Normal mode is still there. Thus you can map | |
| 61 the same key differently for each mode. | |
| 62 Notice that, although this mapping starts in Insert mode, it ends in Normal | |
| 42 | 63 mode. If you want it to continue in Insert mode, append an "a" to the |
| 64 mapping. | |
| 7 | 65 |
| 66 Here is an overview of map commands and in which mode they work: | |
| 67 | |
| 68 :map Normal, Visual and Operator-pending | |
| 69 :vmap Visual | |
| 70 :nmap Normal | |
| 71 :omap Operator-pending | |
| 72 :map! Insert and Command-line | |
| 73 :imap Insert | |
| 74 :cmap Command-line | |
| 75 | |
| 76 Operator-pending mode is when you typed an operator character, such as "d" or | |
| 77 "y", and you are expected to type the motion command or a text object. Thus | |
| 78 when you type "dw", the "w" is entered in operator-pending mode. | |
| 79 | |
| 80 Suppose that you want to define <F7> so that the command d<F7> deletes a C | |
| 81 program block (text enclosed in curly braces, {}). Similarly y<F7> would yank | |
| 82 the program block into the unnamed register. Therefore, what you need to do | |
| 83 is to define <F7> to select the current program block. You can do this with | |
| 84 the following command: > | |
| 85 | |
| 86 :omap <F7> a{ | |
| 87 | |
| 88 This causes <F7> to perform a select block "a{" in operator-pending mode, just | |
| 89 like you typed it. This mapping is useful if typing a { on your keyboard is a | |
| 90 bit difficult. | |
| 91 | |
| 92 | |
| 93 LISTING MAPPINGS | |
| 94 | |
| 95 To see the currently defined mappings, use ":map" without arguments. Or one | |
| 96 of the variants that include the mode in which they work. The output could | |
| 97 look like this: | |
| 98 | |
| 99 _g :call MyGrep(1)<CR> ~ | |
| 100 v <F2> :s/^/> /<CR>:noh<CR>`` ~ | |
| 101 n <F2> :.,$s/^/> /<CR>:noh<CR>`` ~ | |
| 102 <xHome> <Home> | |
| 103 <xEnd> <End> | |
| 104 | |
| 105 | |
| 106 The first column of the list shows in which mode the mapping is effective. | |
| 107 This is "n" for Normal mode, "i" for Insert mode, etc. A blank is used for a | |
| 108 mapping defined with ":map", thus effective in both Normal and Visual mode. | |
| 109 One useful purpose of listing the mapping is to check if special keys in <> | |
| 110 form have been recognized (this only works when color is supported). For | |
| 111 example, when <Esc> is displayed in color, it stands for the escape character. | |
| 112 When it has the same color as the other text, it is five characters. | |
| 113 | |
| 114 | |
| 115 REMAPPING | |
| 116 | |
| 117 The result of a mapping is inspected for other mappings in it. For example, | |
| 118 the mappings for <F2> above could be shortened to: > | |
| 119 | |
| 120 :map <F2> G<F3> | |
| 121 :imap <F2> <Esc><F3> | |
| 122 :map <F3> oDate: <Esc>:read !date<CR>kJ | |
| 123 | |
| 124 For Normal mode <F2> is mapped to go to the last line, and then behave like | |
| 125 <F3> was pressed. In Insert mode <F2> stops Insert mode with <Esc> and then | |
| 126 also uses <F3>. Then <F3> is mapped to do the actual work. | |
| 127 | |
| 128 Suppose you hardly ever use Ex mode, and want to use the "Q" command to format | |
| 129 text (this was so in old versions of Vim). This mapping will do it: > | |
| 130 | |
| 131 :map Q gq | |
| 132 | |
| 133 But, in rare cases you need to use Ex mode anyway. Let's map "gQ" to Q, so | |
| 134 that you can still go to Ex mode: > | |
| 135 | |
| 136 :map gQ Q | |
| 137 | |
| 138 What happens now is that when you type "gQ" it is mapped to "Q". So far so | |
| 139 good. But then "Q" is mapped to "gq", thus typing "gQ" results in "gq", and | |
| 140 you don't get to Ex mode at all. | |
| 141 To avoid keys to be mapped again, use the ":noremap" command: > | |
| 142 | |
| 143 :noremap gQ Q | |
| 144 | |
| 145 Now Vim knows that the "Q" is not to be inspected for mappings that apply to | |
| 146 it. There is a similar command for every mode: | |
| 147 | |
| 148 :noremap Normal, Visual and Operator-pending | |
| 149 :vnoremap Visual | |
| 150 :nnoremap Normal | |
| 151 :onoremap Operator-pending | |
| 152 :noremap! Insert and Command-line | |
| 153 :inoremap Insert | |
| 154 :cnoremap Command-line | |
| 155 | |
| 156 | |
| 157 RECURSIVE MAPPING | |
| 158 | |
| 159 When a mapping triggers itself, it will run forever. This can be used to | |
| 160 repeat an action an unlimited number of times. | |
| 161 For example, you have a list of files that contain a version number in the | |
| 162 first line. You edit these files with "vim *.txt". You are now editing the | |
| 163 first file. Define this mapping: > | |
| 164 | |
| 165 :map ,, :s/5.1/5.2/<CR>:wnext<CR>,, | |
| 166 | |
| 167 Now you type ",,". This triggers the mapping. It replaces "5.1" with "5.2" | |
| 168 in the first line. Then it does a ":wnext" to write the file and edit the | |
| 169 next one. The mapping ends in ",,". This triggers the same mapping again, | |
| 170 thus doing the substitution, etc. | |
| 171 This continues until there is an error. In this case it could be a file | |
| 172 where the substitute command doesn't find a match for "5.1". You can then | |
| 173 make a change to insert "5.1" and continue by typing ",," again. Or the | |
| 174 ":wnext" fails, because you are in the last file in the list. | |
| 175 When a mapping runs into an error halfway, the rest of the mapping is | |
| 176 discarded. CTRL-C interrupts the mapping (CTRL-Break on MS-Windows). | |
| 177 | |
| 178 | |
| 179 DELETE A MAPPING | |
| 180 | |
| 181 To remove a mapping use the ":unmap" command. Again, the mode the unmapping | |
| 182 applies to depends on the command used: | |
| 183 | |
| 184 :unmap Normal, Visual and Operator-pending | |
| 185 :vunmap Visual | |
| 186 :nunmap Normal | |
| 187 :ounmap Operator-pending | |
| 188 :unmap! Insert and Command-line | |
| 189 :iunmap Insert | |
| 190 :cunmap Command-line | |
| 191 | |
| 192 There is a trick to define a mapping that works in Normal and Operator-pending | |
| 193 mode, but not in Visual mode. First define it for all three modes, then | |
| 194 delete it for Visual mode: > | |
| 195 | |
| 196 :map <C-A> /---><CR> | |
| 197 :vunmap <C-A> | |
| 198 | |
| 199 Notice that the five characters "<C-A>" stand for the single key CTRL-A. | |
| 200 | |
| 201 To remove all mappings use the |:mapclear| command. You can guess the | |
| 202 variations for different modes by now. Be careful with this command, it can't | |
| 203 be undone. | |
| 204 | |
| 205 | |
| 206 SPECIAL CHARACTERS | |
| 207 | |
| 208 The ":map" command can be followed by another command. A | character | |
| 209 separates the two commands. This also means that a | character can't be used | |
| 210 inside a map command. To include one, use <Bar> (five characters). Example: | |
| 211 > | |
| 5690 | 212 :map <F8> :write <Bar> !checkin %:S<CR> |
| 7 | 213 |
| 214 The same problem applies to the ":unmap" command, with the addition that you | |
| 215 have to watch out for trailing white space. These two commands are different: | |
| 216 > | |
| 217 :unmap a | unmap b | |
| 218 :unmap a| unmap b | |
| 219 | |
| 220 The first command tries to unmap "a ", with a trailing space. | |
| 221 | |
| 222 When using a space inside a mapping, use <Space> (seven characters): > | |
| 223 | |
| 224 :map <Space> W | |
| 225 | |
| 226 This makes the spacebar move a blank-separated word forward. | |
| 227 | |
| 228 It is not possible to put a comment directly after a mapping, because the " | |
| 229 character is considered to be part of the mapping. You can use |", this | |
| 230 starts a new, empty command with a comment. Example: > | |
| 231 | |
| 232 :map <Space> W| " Use spacebar to move forward a word | |
| 233 | |
| 234 | |
| 235 MAPPINGS AND ABBREVIATIONS | |
| 236 | |
| 237 Abbreviations are a lot like Insert mode mappings. The arguments are handled | |
| 238 in the same way. The main difference is the way they are triggered. An | |
| 239 abbreviation is triggered by typing a non-word character after the word. A | |
| 240 mapping is triggered when typing the last character. | |
| 241 Another difference is that the characters you type for an abbreviation are | |
| 242 inserted in the text while you type them. When the abbreviation is triggered | |
| 243 these characters are deleted and replaced by what the abbreviation produces. | |
| 244 When typing the characters for a mapping, nothing is inserted until you type | |
| 245 the last character that triggers it. If the 'showcmd' option is set, the | |
| 246 typed characters are displayed in the last line of the Vim window. | |
| 247 An exception is when a mapping is ambiguous. Suppose you have done two | |
| 248 mappings: > | |
| 249 | |
| 250 :imap aa foo | |
| 251 :imap aaa bar | |
| 252 | |
| 253 Now, when you type "aa", Vim doesn't know if it should apply the first or the | |
| 254 second mapping. It waits for another character to be typed. If it is an "a", | |
| 255 the second mapping is applied and results in "bar". If it is a space, for | |
| 256 example, the first mapping is applied, resulting in "foo", and then the space | |
| 257 is inserted. | |
| 258 | |
| 259 | |
| 260 ADDITIONALLY... | |
| 261 | |
| 262 The <script> keyword can be used to make a mapping local to a script. See | |
| 263 |:map-<script>|. | |
| 264 | |
| 265 The <buffer> keyword can be used to make a mapping local to a specific buffer. | |
| 266 See |:map-<buffer>| | |
| 267 | |
| 268 The <unique> keyword can be used to make defining a new mapping fail when it | |
| 269 already exists. Otherwise a new mapping simply overwrites the old one. See | |
| 270 |:map-<unique>|. | |
| 271 | |
| 272 To make a key do nothing, map it to <Nop> (five characters). This will make | |
| 273 the <F7> key do nothing at all: > | |
| 274 | |
| 275 :map <F7> <Nop>| map! <F7> <Nop> | |
| 276 | |
| 277 There must be no space after <Nop>. | |
| 278 | |
| 279 ============================================================================== | |
| 280 *40.2* Defining command-line commands | |
| 281 | |
| 282 The Vim editor enables you to define your own commands. You execute these | |
| 283 commands just like any other Command-line mode command. | |
| 284 To define a command, use the ":command" command, as follows: > | |
| 285 | |
| 286 :command DeleteFirst 1delete | |
| 287 | |
| 288 Now when you execute the command ":DeleteFirst" Vim executes ":1delete", which | |
| 289 deletes the first line. | |
| 290 | |
| 291 Note: | |
| 292 User-defined commands must start with a capital letter. You cannot | |
| 293 use ":X", ":Next" and ":Print". The underscore cannot be used! You | |
| 294 can use digits, but this is discouraged. | |
| 295 | |
| 296 To list the user-defined commands, execute the following command: > | |
| 297 | |
| 298 :command | |
| 299 | |
| 300 Just like with the builtin commands, the user defined commands can be | |
| 301 abbreviated. You need to type just enough to distinguish the command from | |
| 302 another. Command line completion can be used to get the full name. | |
| 303 | |
| 304 | |
| 305 NUMBER OF ARGUMENTS | |
| 306 | |
| 307 User-defined commands can take a series of arguments. The number of arguments | |
| 308 must be specified by the -nargs option. For instance, the example | |
| 309 :DeleteFirst command takes no arguments, so you could have defined it as | |
| 310 follows: > | |
| 311 | |
| 312 :command -nargs=0 DeleteFirst 1delete | |
| 313 | |
| 314 However, because zero arguments is the default, you do not need to add | |
| 315 "-nargs=0". The other values of -nargs are as follows: | |
| 316 | |
| 317 -nargs=0 No arguments | |
| 318 -nargs=1 One argument | |
| 319 -nargs=* Any number of arguments | |
| 320 -nargs=? Zero or one argument | |
| 321 -nargs=+ One or more arguments | |
| 322 | |
| 323 | |
| 324 USING THE ARGUMENTS | |
| 325 | |
| 326 Inside the command definition, the arguments are represented by the | |
| 327 <args> keyword. For example: > | |
| 328 | |
| 329 :command -nargs=+ Say :echo "<args>" | |
| 330 | |
| 331 Now when you type > | |
| 332 | |
| 333 :Say Hello World | |
| 334 | |
| 335 Vim echoes "Hello World". However, if you add a double quote, it won't work. | |
| 336 For example: > | |
| 337 | |
| 338 :Say he said "hello" | |
| 339 | |
| 340 To get special characters turned into a string, properly escaped to use as an | |
| 341 expression, use "<q-args>": > | |
| 342 | |
| 343 :command -nargs=+ Say :echo <q-args> | |
| 344 | |
| 345 Now the above ":Say" command will result in this to be executed: > | |
| 346 | |
| 347 :echo "he said \"hello\"" | |
| 348 | |
| 349 The <f-args> keyword contains the same information as the <args> keyword, | |
| 350 except in a format suitable for use as function call arguments. For example: | |
| 351 > | |
| 352 :command -nargs=* DoIt :call AFunction(<f-args>) | |
| 353 :DoIt a b c | |
| 354 | |
| 355 Executes the following command: > | |
| 356 | |
| 357 :call AFunction("a", "b", "c") | |
| 358 | |
| 359 | |
| 360 LINE RANGE | |
| 361 | |
| 362 Some commands take a range as their argument. To tell Vim that you are | |
| 363 defining such a command, you need to specify a -range option. The values for | |
| 364 this option are as follows: | |
| 365 | |
| 366 -range Range is allowed; default is the current line. | |
| 367 -range=% Range is allowed; default is the whole file. | |
| 368 -range={count} Range is allowed; the last number in it is used as a | |
| 369 single number whose default is {count}. | |
| 370 | |
| 371 When a range is specified, the keywords <line1> and <line2> get the values of | |
| 372 the first and last line in the range. For example, the following command | |
| 373 defines the SaveIt command, which writes out the specified range to the file | |
| 374 "save_file": > | |
| 375 | |
| 376 :command -range=% SaveIt :<line1>,<line2>write! save_file | |
| 377 | |
| 378 | |
| 379 OTHER OPTIONS | |
| 380 | |
| 381 Some of the other options and keywords are as follows: | |
| 382 | |
| 383 -count={number} The command can take a count whose default is | |
| 384 {number}. The resulting count can be used | |
| 385 through the <count> keyword. | |
| 237 | 386 -bang You can use a !. If present, using <bang> will |
| 7 | 387 result in a !. |
| 237 | 388 -register You can specify a register. (The default is |
| 7 | 389 the unnamed register.) |
| 390 The register specification is available as | |
| 391 <reg> (a.k.a. <register>). | |
| 392 -complete={type} Type of command-line completion used. See | |
| 393 |:command-completion| for the list of possible | |
| 394 values. | |
| 395 -bar The command can be followed by | and another | |
| 396 command, or " and a comment. | |
| 397 -buffer The command is only available for the current | |
| 398 buffer. | |
| 399 | |
| 400 Finally, you have the <lt> keyword. It stands for the character <. Use this | |
| 401 to escape the special meaning of the <> items mentioned. | |
| 402 | |
| 403 | |
| 404 REDEFINING AND DELETING | |
| 405 | |
| 406 To redefine the same command use the ! argument: > | |
| 407 | |
| 408 :command -nargs=+ Say :echo "<args>" | |
| 409 :command! -nargs=+ Say :echo <q-args> | |
| 410 | |
| 411 To delete a user command use ":delcommand". It takes a single argument, which | |
| 412 is the name of the command. Example: > | |
| 413 | |
| 414 :delcommand SaveIt | |
| 415 | |
| 416 To delete all the user commands: > | |
| 417 | |
| 418 :comclear | |
| 419 | |
| 420 Careful, this can't be undone! | |
| 421 | |
| 422 More details about all this in the reference manual: |user-commands|. | |
| 423 | |
| 424 ============================================================================== | |
| 425 *40.3* Autocommands | |
| 426 | |
| 427 An autocommand is a command that is executed automatically in response to some | |
| 237 | 428 event, such as a file being read or written or a buffer change. Through the |
| 7 | 429 use of autocommands you can train Vim to edit compressed files, for example. |
| 430 That is used in the |gzip| plugin. | |
| 431 Autocommands are very powerful. Use them with care and they will help you | |
| 432 avoid typing many commands. Use them carelessly and they will cause a lot of | |
| 433 trouble. | |
| 434 | |
| 237 | 435 Suppose you want to replace a datestamp on the end of a file every time it is |
| 7 | 436 written. First you define a function: > |
| 437 | |
| 438 :function DateInsert() | |
| 439 : $delete | |
| 440 : read !date | |
| 441 :endfunction | |
| 442 | |
| 5294 | 443 You want this function to be called each time, just before a buffer is written |
| 444 to a file. This will make that happen: > | |
| 7 | 445 |
| 5294 | 446 :autocmd BufWritePre * call DateInsert() |
| 7 | 447 |
| 5294 | 448 "BufWritePre" is the event for which this autocommand is triggered: Just |
| 449 before (pre) writing a buffer to a file. The "*" is a pattern to match with | |
| 450 the file name. In this case it matches all files. | |
| 7 | 451 With this command enabled, when you do a ":write", Vim checks for any |
| 5294 | 452 matching BufWritePre autocommands and executes them, and then it |
| 7 | 453 performs the ":write". |
| 454 The general form of the :autocmd command is as follows: > | |
| 455 | |
| 22171 | 456 :autocmd [group] {events} {file-pattern} [++nested] {command} |
| 7 | 457 |
| 458 The [group] name is optional. It is used in managing and calling the commands | |
| 459 (more on this later). The {events} parameter is a list of events (comma | |
| 460 separated) that trigger the command. | |
| 21676 | 461 {file-pattern} is a filename, usually with wildcards. For example, using |
| 7 | 462 "*.txt" makes the autocommand be used for all files whose name end in ".txt". |
| 22171 | 463 The optional [++nested] flag allows for nesting of autocommands (see below), |
| 464 and finally, {command} is the command to be executed. | |
| 7 | 465 |
| 29269 | 466 When adding an autocommand the already existing ones remain. To avoid adding |
| 29274 | 467 the autocommand several times you should use this form: > |
| 29269 | 468 |
| 469 :augroup updateDate | |
| 470 : autocmd! | |
| 471 : autocmd BufWritePre * call DateInsert() | |
| 472 :augroup END | |
| 473 | |
| 474 This will delete any previously defined autocommand with `:autocmd!` before | |
| 475 defining the new one. Groups are explained later. | |
| 476 | |
| 7 | 477 |
| 478 EVENTS | |
| 479 | |
| 480 One of the most useful events is BufReadPost. It is triggered after a new | |
| 481 file is being edited. It is commonly used to set option values. For example, | |
| 482 you know that "*.gsm" files are GNU assembly language. To get the syntax file | |
| 483 right, define this autocommand: > | |
| 484 | |
| 485 :autocmd BufReadPost *.gsm set filetype=asm | |
| 486 | |
| 487 If Vim is able to detect the type of file, it will set the 'filetype' option | |
| 488 for you. This triggers the Filetype event. Use this to do something when a | |
| 489 certain type of file is edited. For example, to load a list of abbreviations | |
| 490 for text files: > | |
| 491 | |
| 492 :autocmd Filetype text source ~/.vim/abbrevs.vim | |
| 493 | |
| 494 When starting to edit a new file, you could make Vim insert a skeleton: > | |
| 495 | |
| 496 :autocmd BufNewFile *.[ch] 0read ~/skeletons/skel.c | |
| 497 | |
| 498 See |autocmd-events| for a complete list of events. | |
| 499 | |
| 500 | |
| 501 PATTERNS | |
| 502 | |
| 21676 | 503 The {file-pattern} argument can actually be a comma-separated list of file |
| 7 | 504 patterns. For example: "*.c,*.h" matches files ending in ".c" and ".h". |
| 505 The usual file wildcards can be used. Here is a summary of the most often | |
| 506 used ones: | |
| 507 | |
| 508 * Match any character any number of times | |
| 509 ? Match any character once | |
| 510 [abc] Match the character a, b or c | |
| 511 . Matches a dot | |
| 512 a{b,c} Matches "ab" and "ac" | |
| 513 | |
| 514 When the pattern includes a slash (/) Vim will compare directory names. | |
| 515 Without the slash only the last part of a file name is used. For example, | |
| 516 "*.txt" matches "/home/biep/readme.txt". The pattern "/home/biep/*" would | |
| 517 also match it. But "home/foo/*.txt" wouldn't. | |
| 518 When including a slash, Vim matches the pattern against both the full path | |
| 519 of the file ("/home/biep/readme.txt") and the relative path (e.g., | |
| 520 "biep/readme.txt"). | |
| 521 | |
| 522 Note: | |
| 523 When working on a system that uses a backslash as file separator, such | |
| 524 as MS-Windows, you still use forward slashes in autocommands. This | |
| 525 makes it easier to write the pattern, since a backslash has a special | |
| 526 meaning. It also makes the autocommands portable. | |
| 527 | |
| 528 | |
| 529 DELETING | |
| 530 | |
| 531 To delete an autocommand, use the same command as what it was defined with, | |
| 532 but leave out the {command} at the end and use a !. Example: > | |
| 533 | |
| 534 :autocmd! FileWritePre * | |
| 535 | |
| 536 This will delete all autocommands for the "FileWritePre" event that use the | |
| 537 "*" pattern. | |
| 538 | |
| 539 | |
| 540 LISTING | |
| 541 | |
| 542 To list all the currently defined autocommands, use this: > | |
| 543 | |
| 544 :autocmd | |
| 545 | |
| 546 The list can be very long, especially when filetype detection is used. To | |
| 547 list only part of the commands, specify the group, event and/or pattern. For | |
| 548 example, to list all BufNewFile autocommands: > | |
| 549 | |
| 550 :autocmd BufNewFile | |
| 551 | |
| 552 To list all autocommands for the pattern "*.c": > | |
| 553 | |
| 554 :autocmd * *.c | |
| 555 | |
| 556 Using "*" for the event will list all the events. To list all autocommands | |
| 557 for the cprograms group: > | |
| 558 | |
| 559 :autocmd cprograms | |
| 560 | |
| 561 | |
| 562 GROUPS | |
| 563 | |
| 564 The {group} item, used when defining an autocommand, groups related autocommands | |
| 565 together. This can be used to delete all the autocommands in a certain group, | |
| 566 for example. | |
| 567 When defining several autocommands for a certain group, use the ":augroup" | |
| 568 command. For example, let's define autocommands for C programs: > | |
| 569 | |
| 570 :augroup cprograms | |
| 571 : autocmd BufReadPost *.c,*.h :set sw=4 sts=4 | |
| 572 : autocmd BufReadPost *.cpp :set sw=3 sts=3 | |
| 573 :augroup END | |
| 574 | |
| 575 This will do the same as: > | |
| 576 | |
| 577 :autocmd cprograms BufReadPost *.c,*.h :set sw=4 sts=4 | |
| 578 :autocmd cprograms BufReadPost *.cpp :set sw=3 sts=3 | |
| 579 | |
| 580 To delete all autocommands in the "cprograms" group: > | |
| 581 | |
| 582 :autocmd! cprograms | |
| 583 | |
| 584 | |
| 585 NESTING | |
| 586 | |
| 587 Generally, commands executed as the result of an autocommand event will not | |
| 588 trigger any new events. If you read a file in response to a FileChangedShell | |
| 589 event, it will not trigger the autocommands that would set the syntax, for | |
| 590 example. To make the events triggered, add the "nested" argument: > | |
| 591 | |
| 22171 | 592 :autocmd FileChangedShell * ++nested edit |
| 7 | 593 |
| 594 | |
| 595 EXECUTING AUTOCOMMANDS | |
| 596 | |
| 597 It is possible to trigger an autocommand by pretending an event has occurred. | |
| 598 This is useful to have one autocommand trigger another one. Example: > | |
| 599 | |
| 600 :autocmd BufReadPost *.new execute "doautocmd BufReadPost " . expand("<afile>:r") | |
| 601 | |
| 602 This defines an autocommand that is triggered when a new file has been edited. | |
| 603 The file name must end in ".new". The ":execute" command uses expression | |
| 604 evaluation to form a new command and execute it. When editing the file | |
| 605 "tryout.c.new" the executed command will be: > | |
| 606 | |
| 607 :doautocmd BufReadPost tryout.c | |
| 608 | |
| 609 The expand() function takes the "<afile>" argument, which stands for the file | |
| 610 name the autocommand was executed for, and takes the root of the file name | |
| 611 with ":r". | |
| 612 | |
| 613 ":doautocmd" executes on the current buffer. The ":doautoall" command works | |
| 614 like "doautocmd" except it executes on all the buffers. | |
| 615 | |
| 616 | |
| 617 USING NORMAL MODE COMMANDS | |
| 618 | |
| 1125 | 619 The commands executed by an autocommand are Command-line commands. If you |
| 620 want to use a Normal mode command, the ":normal" command can be used. | |
| 621 Example: > | |
| 7 | 622 |
| 623 :autocmd BufReadPost *.log normal G | |
| 624 | |
| 625 This will make the cursor jump to the last line of *.log files when you start | |
| 626 to edit it. | |
| 627 Using the ":normal" command is a bit tricky. First of all, make sure its | |
| 628 argument is a complete command, including all the arguments. When you use "i" | |
| 629 to go to Insert mode, there must also be a <Esc> to leave Insert mode again. | |
| 630 If you use a "/" to start a search pattern, there must be a <CR> to execute | |
| 631 it. | |
| 632 The ":normal" command uses all the text after it as commands. Thus there | |
| 633 can be no | and another command following. To work around this, put the | |
| 634 ":normal" command inside an ":execute" command. This also makes it possible | |
| 635 to pass unprintable characters in a convenient way. Example: > | |
| 636 | |
| 637 :autocmd BufReadPost *.chg execute "normal ONew entry:\<Esc>" | | |
| 638 \ 1read !date | |
| 639 | |
| 640 This also shows the use of a backslash to break a long command into more | |
| 641 lines. This can be used in Vim scripts (not at the command line). | |
| 642 | |
| 643 When you want the autocommand do something complicated, which involves jumping | |
| 644 around in the file and then returning to the original position, you may want | |
| 645 to restore the view on the file. See |restore-position| for an example. | |
| 646 | |
| 647 | |
| 648 IGNORING EVENTS | |
| 649 | |
| 650 At times, you will not want to trigger an autocommand. The 'eventignore' | |
| 651 option contains a list of events that will be totally ignored. For example, | |
| 652 the following causes events for entering and leaving a window to be ignored: > | |
| 653 | |
| 654 :set eventignore=WinEnter,WinLeave | |
| 655 | |
| 656 To ignore all events, use the following command: > | |
| 657 | |
| 658 :set eventignore=all | |
| 659 | |
| 660 To set it back to the normal behavior, make 'eventignore' empty: > | |
| 661 | |
| 662 :set eventignore= | |
| 663 | |
| 664 ============================================================================== | |
| 665 | |
| 666 Next chapter: |usr_41.txt| Write a Vim script | |
| 667 | |
| 14519 | 668 Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: |