blob: d85e580f51ce3d622c9389873a07d58f12955fa9 [file] [log] [blame]
Christian Brabandt4bfb8992024-10-16 21:58:17 +02001*repeat.txt* For Vim version 9.1. Last change: 2024 Oct 16
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7Repeating commands, Vim scripts and debugging *repeating*
8
9Chapter 26 of the user manual introduces repeating |usr_26.txt|.
10
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100111. Single repeats |single-repeat|
122. Multiple repeats |multi-repeat|
133. Complex repeats |complex-repeat|
144. Using Vim scripts |using-scripts|
155. Using Vim packages |packages|
166. Creating Vim packages |package-create|
177. Debugging scripts |debug-scripts|
188. Profiling |profiling|
Bram Moolenaar071d4272004-06-13 20:20:40 +000019
20==============================================================================
211. Single repeats *single-repeat*
22
23 *.*
24. Repeat last change, with count replaced with [count].
25 Also repeat a yank command, when the 'y' flag is
Bram Moolenaard4755bb2004-09-02 19:12:26 +000026 included in 'cpoptions'. Does not repeat a
27 command-line command.
Bram Moolenaar071d4272004-06-13 20:20:40 +000028
29Simple changes can be repeated with the "." command. Without a count, the
30count of the last change is used. If you enter a count, it will replace the
Bram Moolenaar92dff182014-02-11 19:15:50 +010031last one. |v:count| and |v:count1| will be set.
32
33If the last change included a specification of a numbered register, the
34register number will be incremented. See |redo-register| for an example how
35to use this.
36
37Note that when repeating a command that used a Visual selection, the same SIZE
38of area is used, see |visual-repeat|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000039
40 *@:*
41@: Repeat last command-line [count] times.
42 {not available when compiled without the
43 |+cmdline_hist| feature}
44
45
46==============================================================================
472. Multiple repeats *multi-repeat*
48
Bram Moolenaarf84b1222017-06-10 14:29:52 +020049 *:g* *:global* *E148*
Bram Moolenaar071d4272004-06-13 20:20:40 +000050:[range]g[lobal]/{pattern}/[cmd]
51 Execute the Ex command [cmd] (default ":p") on the
52 lines within [range] where {pattern} matches.
53
54:[range]g[lobal]!/{pattern}/[cmd]
55 Execute the Ex command [cmd] (default ":p") on the
56 lines within [range] where {pattern} does NOT match.
57
58 *:v* *:vglobal*
59:[range]v[global]/{pattern}/[cmd]
60 Same as :g!.
61
Bram Moolenaar3ec32172021-05-16 12:39:47 +020062Example: >
63 :g/^Obsolete/d _
64Using the underscore after `:d` avoids clobbering registers or the clipboard.
65This also makes it faster.
66
Bram Moolenaarc81e5e72007-05-05 18:24:42 +000067Instead of the '/' which surrounds the {pattern}, you can use any other
Bram Moolenaarb7398fe2023-05-14 18:50:25 +010068single byte character, but not an alphabetic character, '\', '"', '|' or '!'.
Bram Moolenaarc81e5e72007-05-05 18:24:42 +000069This is useful if you want to include a '/' in the search pattern or
70replacement string.
71
72For the definition of a pattern, see |pattern|.
73
Bram Moolenaar32efaf62014-11-05 17:02:17 +010074NOTE [cmd] may contain a range; see |collapse| and |edit-paragraph-join| for
75examples.
76
Bram Moolenaar071d4272004-06-13 20:20:40 +000077The global commands work by first scanning through the [range] lines and
78marking each line where a match occurs (for a multi-line pattern, only the
79start of the match matters).
Bram Moolenaar03413f42016-04-12 21:07:15 +020080In a second scan the [cmd] is executed for each marked line, as if the cursor
81was in that line. For ":v" and ":g!" the command is executed for each not
Bram Moolenaar071d4272004-06-13 20:20:40 +000082marked line. If a line is deleted its mark disappears.
83The default for [range] is the whole buffer (1,$). Use "CTRL-C" to interrupt
84the command. If an error message is given for a line, the command for that
85line is aborted and the global command continues with the next marked or
86unmarked line.
Bram Moolenaar664f3cf2019-12-07 16:03:51 +010087 *E147*
Bram Moolenaarf84b1222017-06-10 14:29:52 +020088When the command is used recursively, it only works on one line. Giving a
89range is then not allowed. This is useful to find all lines that match a
90pattern and do not match another pattern: >
91 :g/found/v/notfound/{cmd}
92This first finds all lines containing "found", but only executes {cmd} when
93there is no match for "notfound".
Bram Moolenaar071d4272004-06-13 20:20:40 +000094
Bram Moolenaar9fbdbb82022-09-27 17:30:34 +010095Any Ex command can be used, see |ex-cmd-index|. To execute a Normal mode
96command, you can use the `:normal` command: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000097 :g/pat/normal {commands}
98Make sure that {commands} ends with a whole command, otherwise Vim will wait
99for you to type the rest of the command for each match. The screen will not
100have been updated, so you don't know what you are doing. See |:normal|.
101
102The undo/redo command will undo/redo the whole global command at once.
103The previous context mark will only be set once (with "''" you go back to
104where the cursor was before the global command).
105
106The global command sets both the last used search pattern and the last used
107substitute pattern (this is vi compatible). This makes it easy to globally
Milly89872f52024-10-05 17:16:18 +0200108replace a string: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000109 :g/pat/s//PAT/g
Milly89872f52024-10-05 17:16:18 +0200110This replaces all occurrences of "pat" with "PAT". The same can be done with: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000111 :%s/pat/PAT/g
112Which is two characters shorter!
113
Bram Moolenaar864207d2008-06-24 22:14:38 +0000114When using "global" in Ex mode, a special case is using ":visual" as a
115command. This will move to a matching line, go to Normal mode to let you
116execute commands there until you use |Q| to return to Ex mode. This will be
117repeated for each matching line. While doing this you cannot use ":global".
118To abort this type CTRL-C twice.
Bram Moolenaar26a60b42005-02-22 08:49:11 +0000119
Bram Moolenaar071d4272004-06-13 20:20:40 +0000120==============================================================================
1213. Complex repeats *complex-repeat*
122
123 *q* *recording*
124q{0-9a-zA-Z"} Record typed characters into register {0-9a-zA-Z"}
125 (uppercase to append). The 'q' command is disabled
126 while executing a register, and it doesn't work inside
Bram Moolenaara0ed84a2015-11-19 17:56:13 +0100127 a mapping and |:normal|.
128
129 Note: If the register being used for recording is also
130 used for |y| and |p| the result is most likely not
131 what is expected, because the put will paste the
132 recorded macro and the yank will overwrite the
Bram Moolenaara6c27c42019-05-09 19:16:22 +0200133 recorded macro.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000134
Bram Moolenaar388a5d42020-05-26 21:20:45 +0200135 Note: The recording happens while you type, replaying
136 the register happens as if the keys come from a
137 mapping. This matters, for example, for undo, which
138 only syncs when commands were typed.
139
Bram Moolenaar071d4272004-06-13 20:20:40 +0000140q Stops recording. (Implementation note: The 'q' that
141 stops recording is not stored in the register, unless
Bram Moolenaara6c27c42019-05-09 19:16:22 +0200142 it was the result of a mapping)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000143
144 *@*
Bram Moolenaar61d35bd2012-03-28 20:51:51 +0200145@{0-9a-z".=*+} Execute the contents of register {0-9a-z".=*+} [count]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000146 times. Note that register '%' (name of the current
147 file) and '#' (name of the alternate file) cannot be
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +0100148 used.
149 The register is executed like a mapping, that means
150 that the difference between 'wildchar' and 'wildcharm'
Bram Moolenaar388a5d42020-05-26 21:20:45 +0200151 applies, and undo might not be synced in the same way.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +0100152 For "@=" you are prompted to enter an expression. The
153 result of the expression is then executed.
Bram Moolenaara6c27c42019-05-09 19:16:22 +0200154 See also |@:|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000155
Bram Moolenaar26a60b42005-02-22 08:49:11 +0000156 *@@* *E748*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000157@@ Repeat the previous @{0-9a-z":*} [count] times.
158
Bram Moolenaar3ec32172021-05-16 12:39:47 +0200159 *:@*
Bram Moolenaar61d35bd2012-03-28 20:51:51 +0200160:[addr]@{0-9a-z".=*+} Execute the contents of register {0-9a-z".=*+} as an Ex
Bram Moolenaar071d4272004-06-13 20:20:40 +0000161 command. First set cursor at line [addr] (default is
162 current line). When the last line in the register does
163 not have a <CR> it will be added automatically when
164 the 'e' flag is present in 'cpoptions'.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000165 For ":@=" the last used expression is used. The
166 result of evaluating the expression is executed as an
167 Ex command.
168 Mappings are not recognized in these commands.
Bram Moolenaar856c1112020-06-17 21:47:23 +0200169 When the |line-continuation| character (\) is present
170 at the beginning of a line in a linewise register,
171 then it is combined with the previous line. This is
172 useful for yanking and executing parts of a Vim
173 script.
Bram Moolenaara6c27c42019-05-09 19:16:22 +0200174 Future: Will execute the register for each line in the
175 address range.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000176
Bram Moolenaar3ec32172021-05-16 12:39:47 +0200177:[addr]*{0-9a-z".=+} *:star-compatible*
178 When '*' is present in 'cpoptions' |cpo-star|, use
179 ":*" in the same way as ":@". This is NOT the default
180 when 'nocompatible' is used. When the '*' flag is not
181 present in 'cpoptions', ":*" is an alias for ":'<,'>",
182 select the Visual area |:star|.
183
Bram Moolenaar071d4272004-06-13 20:20:40 +0000184 *:@:*
185:[addr]@: Repeat last command-line. First set cursor at line
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200186 [addr] (default is current line).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000187
Bram Moolenaar7e1479b2016-09-11 15:07:27 +0200188:[addr]@ *:@@*
Bram Moolenaar7ceefb32020-05-01 16:07:38 +0200189:[addr]@@ Repeat the previous :@{register}. First set cursor at
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200190 line [addr] (default is current line).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000191
192==============================================================================
1934. Using Vim scripts *using-scripts*
194
195For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|.
196
197 *:so* *:source* *load-vim-script*
198:so[urce] {file} Read Ex commands from {file}. These are commands that
199 start with a ":".
Bram Moolenaar1f35bf92006-03-07 22:38:47 +0000200 Triggers the |SourcePre| autocommand.
Bram Moolenaard799daa2022-06-20 11:17:32 +0100201 *:source-range*
Yegappan Lakshmanan35dc1762022-03-22 12:13:54 +0000202:[range]so[urce] [++clear]
203 Read Ex commands from the [range] of lines in the
Bram Moolenaar9fbdbb82022-09-27 17:30:34 +0100204 current buffer. When [range] is omitted read all
205 lines.
Yegappan Lakshmanan35dc1762022-03-22 12:13:54 +0000206
207 When sourcing commands from the current buffer, the
208 same script-ID |<SID>| is used even if the buffer is
209 sourced multiple times. If a buffer is sourced more
210 than once, then the functions in the buffer are
211 defined again.
212
213 To source a range of lines that doesn't start with the
214 |:vim9script| command in Vim9 script context, the
Bram Moolenaar46eea442022-03-30 10:51:39 +0100215 |:vim9cmd| modifier can be used. If you use a Visual
216 selection and type ":", the range in the form "'<,'>"
217 can come before it: >
218 :'<,'>vim9cmd source
219< Otherwise the range goes after the modifier and must
220 have a colon prefixed, like all Vim9 ranges: >
221 :vim9cmd :5,9source
Yegappan Lakshmanan35dc1762022-03-22 12:13:54 +0000222
Bram Moolenaar46eea442022-03-30 10:51:39 +0100223< When a range of lines in a buffer is sourced in the
Yegappan Lakshmanan35dc1762022-03-22 12:13:54 +0000224 Vim9 script context, the previously defined
225 script-local variables and functions are not cleared.
226 This works like the range started with the
227 ":vim9script noclear" command. The "++clear" argument
228 can be used to clear the script-local variables and
229 functions before sourcing the script. This works like
Bram Moolenaar46eea442022-03-30 10:51:39 +0100230 the range started with the `:vim9script` command
Yegappan Lakshmanan35dc1762022-03-22 12:13:54 +0000231 without the "noclear" argument. See |vim9-reload| for
232 more information.
233 Examples: >
Yegappan Lakshmanan35dc1762022-03-22 12:13:54 +0000234 :4,5source
Yegappan Lakshmanan35dc1762022-03-22 12:13:54 +0000235 :10,18source ++clear
Bram Moolenaarb529cfb2022-07-25 15:42:07 +0100236<
Bram Moolenaar68e65602019-05-26 21:33:31 +0200237 *:source!*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000238:so[urce]! {file} Read Vim commands from {file}. These are commands
239 that are executed from Normal mode, like you type
240 them.
241 When used after |:global|, |:argdo|, |:windo|,
242 |:bufdo|, in a loop or when another command follows
243 the display won't be updated while executing the
244 commands.
Bram Moolenaar68e65602019-05-26 21:33:31 +0200245 Cannot be used in the |sandbox|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000246
247 *:ru* *:runtime*
Bram Moolenaar8dcf2592016-03-12 22:47:14 +0100248:ru[ntime][!] [where] {file} ..
Bram Moolenaar071d4272004-06-13 20:20:40 +0000249 Read Ex commands from {file} in each directory given
Bram Moolenaar8dcf2592016-03-12 22:47:14 +0100250 by 'runtimepath' and/or 'packpath'. There is no error
251 for non-existing files.
Bram Moolenaar664f3cf2019-12-07 16:03:51 +0100252
Bram Moolenaar8dcf2592016-03-12 22:47:14 +0100253 Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000254 :runtime syntax/c.vim
255
256< There can be multiple {file} arguments, separated by
257 spaces. Each {file} is searched for in the first
258 directory from 'runtimepath', then in the second
259 directory, etc. Use a backslash to include a space
260 inside {file} (although it's better not to use spaces
261 in file names, it causes trouble).
262
263 When [!] is included, all found files are sourced.
264 When it is not included only the first found file is
265 sourced.
266
Bram Moolenaar8dcf2592016-03-12 22:47:14 +0100267 When [where] is omitted only 'runtimepath' is used.
268 Other values:
269 START search under "start" in 'packpath'
Bram Moolenaar938ae282023-02-20 20:44:55 +0000270 OPT search under "opt" in 'packpath'
Bram Moolenaar8dcf2592016-03-12 22:47:14 +0100271 PACK search under "start" and "opt" in
272 'packpath'
273 ALL first use 'runtimepath', then search
274 under "start" and "opt" in 'packpath'
275
Bram Moolenaar071d4272004-06-13 20:20:40 +0000276 When {file} contains wildcards it is expanded to all
277 matching files. Example: >
Bram Moolenaar589edb32019-09-20 14:38:13 +0200278 :runtime! plugin/**/*.vim
Bram Moolenaar071d4272004-06-13 20:20:40 +0000279< This is what Vim uses to load the plugin files when
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000280 starting up. This similar command: >
Bram Moolenaar589edb32019-09-20 14:38:13 +0200281 :runtime plugin/**/*.vim
Bram Moolenaar071d4272004-06-13 20:20:40 +0000282< would source the first file only.
283
284 When 'verbose' is one or higher, there is a message
285 when no file could be found.
286 When 'verbose' is two or higher, there is a message
287 about each searched file.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000288
Bram Moolenaarbe82c252016-03-06 14:44:08 +0100289 *:pa* *:packadd* *E919*
Bram Moolenaar328da0d2016-03-04 22:22:32 +0100290:pa[ckadd][!] {name} Search for an optional plugin directory in 'packpath'
291 and source any plugin files found. The directory must
292 match:
293 pack/*/opt/{name} ~
294 The directory is added to 'runtimepath' if it wasn't
295 there yet.
Bram Moolenaar26852122016-05-24 20:02:38 +0200296 If the directory pack/*/opt/{name}/after exists it is
297 added at the end of 'runtimepath'.
Bram Moolenaardae8d212016-02-27 22:40:16 +0100298
Bram Moolenaarf0b03c42017-12-17 17:17:07 +0100299 If loading packages from "pack/*/start" was skipped,
300 then this directory is searched first:
301 pack/*/start/{name} ~
302
Bram Moolenaarf6fee0e2016-02-21 23:02:49 +0100303 Note that {name} is the directory name, not the name
Bram Moolenaar03413f42016-04-12 21:07:15 +0200304 of the .vim file. All the files matching the pattern
305 pack/*/opt/{name}/plugin/**/*.vim ~
306 will be sourced. This allows for using subdirectories
307 below "plugin", just like with plugins in
308 'runtimepath'.
Bram Moolenaarf6fee0e2016-02-21 23:02:49 +0100309
Bram Moolenaar328da0d2016-03-04 22:22:32 +0100310 If the filetype detection was not enabled yet (this
Bram Moolenaar10e8ff92023-06-10 21:40:39 +0100311 is usually done with a `syntax enable` or `filetype on`
312 command in your .vimrc file), this will also look
Bram Moolenaar328da0d2016-03-04 22:22:32 +0100313 for "{name}/ftdetect/*.vim" files.
314
315 When the optional ! is added no plugin files or
316 ftdetect scripts are loaded, only the matching
317 directories are added to 'runtimepath'. This is
318 useful in your .vimrc. The plugins will then be
Bram Moolenaar2346a632021-06-13 19:02:49 +0200319 loaded during initialization, see |load-plugins| (note
320 that the loading order will be reversed, because each
321 directory is inserted before others).
Bram Moolenaar4f4d51a2020-10-11 13:57:40 +0200322 Note that for ftdetect scripts to be loaded
323 you will need to write `filetype plugin indent on`
324 AFTER all `packadd!` commands.
Bram Moolenaar328da0d2016-03-04 22:22:32 +0100325
326 Also see |pack-add|.
Bram Moolenaar6dc819b2018-07-03 16:42:19 +0200327 {only available when compiled with |+eval|}
Bram Moolenaar328da0d2016-03-04 22:22:32 +0100328
Bram Moolenaare18c0b32016-03-20 21:08:34 +0100329 *:packl* *:packloadall*
Bram Moolenaar03413f42016-04-12 21:07:15 +0200330:packl[oadall][!] Load all packages in the "start" directory under each
331 entry in 'packpath'.
Bram Moolenaar664f3cf2019-12-07 16:03:51 +0100332
Bram Moolenaar03413f42016-04-12 21:07:15 +0200333 First all the directories found are added to
334 'runtimepath', then the plugins found in the
335 directories are sourced. This allows for a plugin to
336 depend on something of another plugin, e.g. an
337 "autoload" directory. See |packload-two-steps| for
338 how this can be useful.
339
Bram Moolenaare18c0b32016-03-20 21:08:34 +0100340 This is normally done automatically during startup,
341 after loading your .vimrc file. With this command it
342 can be done earlier.
Bram Moolenaar03413f42016-04-12 21:07:15 +0200343
Bram Moolenaar6c1e1572019-06-22 02:13:00 +0200344 Packages will be loaded only once. Using
345 `:packloadall` a second time will have no effect.
346 When the optional ! is added this command will load
347 packages even when done before.
348
349 Note that when using `:packloadall` in the |vimrc|
350 file, the 'runtimepath' option is updated, and later
351 all plugins in 'runtimepath' will be loaded, which
352 means they are loaded again. Plugins are expected to
353 handle that.
Bram Moolenaar03413f42016-04-12 21:07:15 +0200354
Bram Moolenaar7db8f6f2016-03-29 23:12:46 +0200355 An error only causes sourcing the script where it
Bram Moolenaare18c0b32016-03-20 21:08:34 +0100356 happens to be aborted, further plugins will be loaded.
Bram Moolenaar8dcf2592016-03-12 22:47:14 +0100357 See |packages|.
Bram Moolenaar6dc819b2018-07-03 16:42:19 +0200358 {only available when compiled with |+eval|}
Bram Moolenaarf6fee0e2016-02-21 23:02:49 +0100359
Bram Moolenaar071d4272004-06-13 20:20:40 +0000360:scripte[ncoding] [encoding] *:scripte* *:scriptencoding* *E167*
361 Specify the character encoding used in the script.
362 The following lines will be converted from [encoding]
363 to the value of the 'encoding' option, if they are
364 different. Examples: >
365 scriptencoding iso-8859-5
366 scriptencoding cp932
367<
368 When [encoding] is empty, no conversion is done. This
369 can be used to restrict conversion to a sequence of
370 lines: >
371 scriptencoding euc-jp
372 ... lines to be converted ...
373 scriptencoding
374 ... not converted ...
375
376< When conversion isn't supported by the system, there
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +0200377 is no error message and no conversion is done. When a
378 line can't be converted there is no error and the
379 original line is kept.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000380
381 Don't use "ucs-2" or "ucs-4", scripts cannot be in
382 these encodings (they would contain NUL bytes).
383 When a sourced script starts with a BOM (Byte Order
Bram Moolenaar06b5d512010-05-22 15:37:44 +0200384 Mark) in utf-8 format Vim will recognize it, no need
Bram Moolenaar071d4272004-06-13 20:20:40 +0000385 to use ":scriptencoding utf-8" then.
386
Bram Moolenaar3df01732017-02-17 22:47:16 +0100387 If you set the 'encoding' option in your |.vimrc|,
388 `:scriptencoding` must be placed after that. E.g.: >
389 set encoding=utf-8
390 scriptencoding utf-8
391<
Bram Moolenaar071d4272004-06-13 20:20:40 +0000392
Bram Moolenaar558ca4a2019-04-04 18:15:38 +0200393:scriptv[ersion] {version} *:scriptv* *:scriptversion*
Bram Moolenaar6f4754b2022-01-23 12:07:04 +0000394 *E999* *E984* *E1040*
Bram Moolenaar62e1bb42019-04-08 16:25:07 +0200395 Specify the version of Vim for the lines that follow
396 in the same file. Only applies at the toplevel of
397 sourced scripts, not inside functions.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +0200398
399 If {version} is higher than what the current Vim
400 version supports E999 will be given. You either need
401 to rewrite the script to make it work with an older
402 Vim version, or update Vim to a newer version. See
403 |vimscript-version| for what changed between versions.
404
Bram Moolenaarfd218c82022-01-18 16:26:24 +0000405:vim9s[cript] [noclear] *:vim9s* *:vim9script*
Bram Moolenaar7e6a5152021-01-02 16:39:53 +0100406 Marks a script file as containing |Vim9-script|
Bram Moolenaar6f4754b2022-01-23 12:07:04 +0000407 commands. Also see |vim9-namespace|. *E1038*
408 Must be the first command in the file. *E1039*
Bram Moolenaar7e6a5152021-01-02 16:39:53 +0100409 For [noclear] see |vim9-reload|.
410 Without the |+eval| feature this changes the syntax
411 for some commands.
Bram Moolenaar39f3b142021-02-14 12:57:36 +0100412 See |:vim9cmd| for executing one command with Vim9
413 syntax and semantics.
Bram Moolenaar2346a632021-06-13 19:02:49 +0200414
Bram Moolenaar8feef4f2015-01-07 16:57:10 +0100415 *:scr* *:scriptnames*
416:scr[iptnames] List all sourced script names, in the order they were
Bram Moolenaarfd218c82022-01-18 16:26:24 +0000417 first encountered. The number is used for the script
418 ID |<SID>|.
Bram Moolenaar6079da72022-01-18 14:16:59 +0000419 For a script that was used with `import autoload` but
420 was not actually sourced yet an "A" is shown after the
421 script ID.
Bram Moolenaar753885b2022-08-24 16:30:36 +0100422 For a script that was referred to by one name but
423 after resolving symbolic links got sourced with
424 another name the other script is after "->". E.g.
425 "20->22" means script 20 was sourced as script 22.
Bram Moolenaardd60c362023-02-27 15:49:53 +0000426 Also see `getscriptinfo()`.
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200427 {not available when compiled without the |+eval|
428 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000429
Bram Moolenaar07dc18f2018-11-30 22:48:32 +0100430:scr[iptnames][!] {scriptId} *:script*
Bram Moolenaar9d87a372018-12-18 21:41:50 +0100431 Edit script {scriptId}. Although ":scriptnames name"
432 works, using ":script name" is recommended.
433 When the current buffer can't be |abandon|ed and the !
434 is not present, the command fails.
Bram Moolenaar07dc18f2018-11-30 22:48:32 +0100435
Bram Moolenaar071d4272004-06-13 20:20:40 +0000436 *:fini* *:finish* *E168*
437:fini[sh] Stop sourcing a script. Can only be used in a Vim
438 script file. This is a quick way to skip the rest of
439 the file. If it is used after a |:try| but before the
440 matching |:finally| (if present), the commands
441 following the ":finally" up to the matching |:endtry|
442 are executed first. This process applies to all
443 nested ":try"s in the script. The outermost ":endtry"
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200444 then stops sourcing the script.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000445
446All commands and command sequences can be repeated by putting them in a named
447register and then executing it. There are two ways to get the commands in the
448register:
449- Use the record command "q". You type the commands once, and while they are
450 being executed they are stored in a register. Easy, because you can see
451 what you are doing. If you make a mistake, "p"ut the register into the
452 file, edit the command sequence, and then delete it into the register
453 again. You can continue recording by appending to the register (use an
454 uppercase letter).
455- Delete or yank the command sequence into the register.
456
457Often used command sequences can be put under a function key with the ':map'
458command.
459
460An alternative is to put the commands in a file, and execute them with the
461':source!' command. Useful for long command sequences. Can be combined with
462the ':map' command to put complicated commands under a function key.
463
Yegappan Lakshmanan85b43c62022-03-21 19:45:17 +0000464The ':source' command reads Ex commands from a file or a buffer line by line.
465You will have to type any needed keyboard input. The ':source!' command reads
466from a script file character by character, interpreting each character as if
467you typed it.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000468
469Example: When you give the ":!ls" command you get the |hit-enter| prompt. If
470you ':source' a file with the line "!ls" in it, you will have to type the
471<Enter> yourself. But if you ':source!' a file with the line ":!ls" in it,
472the next characters from that file are read until a <CR> is found. You will
473not have to type <CR> yourself, unless ":!ls" was the last line in the file.
474
475It is possible to put ':source[!]' commands in the script file, so you can
476make a top-down hierarchy of script files. The ':source' command can be
477nested as deep as the number of files that can be opened at one time (about
47815). The ':source!' command can be nested up to 15 levels deep.
479
480You can use the "<sfile>" string (literally, this is not a special key) inside
481of the sourced file, in places where a file name is expected. It will be
482replaced by the file name of the sourced file. For example, if you have a
483"other.vimrc" file in the same directory as your ".vimrc" file, you can source
484it from your ".vimrc" file with this command: >
485 :source <sfile>:h/other.vimrc
486
487In script files terminal-dependent key codes are represented by
488terminal-independent two character codes. This means that they can be used
489in the same way on different kinds of terminals. The first character of a
490key code is 0x80 or 128, shown on the screen as "~@". The second one can be
491found in the list |key-notation|. Any of these codes can also be entered
492with CTRL-V followed by the three digit decimal code. This does NOT work for
493the <t_xx> termcap codes, these can only be used in mappings.
494
495 *:source_crnl* *W15*
Bram Moolenaar6f345a12019-12-17 21:27:18 +0100496Win32: Files that are read with ":source" normally have <CR><NL> <EOL>s.
497These always work. If you are using a file with <NL> <EOL>s (for example, a
498file made on Unix), this will be recognized if 'fileformats' is not empty and
499the first line does not end in a <CR>. This fails if the first line has
500something like ":map <F1> :help^M", where "^M" is a <CR>. If the first line
501ends in a <CR>, but following ones don't, you will get an error message,
502because the <CR> from the first lines will be lost.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000503
Bram Moolenaar520470a2005-06-16 21:59:56 +0000504Mac Classic: Files that are read with ":source" normally have <CR> <EOL>s.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000505These always work. If you are using a file with <NL> <EOL>s (for example, a
506file made on Unix), this will be recognized if 'fileformats' is not empty and
507the first line does not end in a <CR>. Be careful not to use a file with <NL>
508linebreaks which has a <CR> in first line.
509
510On other systems, Vim expects ":source"ed files to end in a <NL>. These
511always work. If you are using a file with <CR><NL> <EOL>s (for example, a
Bram Moolenaar5666fcd2019-12-26 14:35:26 +0100512file made on MS-Windows), all lines will have a trailing <CR>. This may cause
Bram Moolenaar071d4272004-06-13 20:20:40 +0000513problems for some commands (e.g., mappings). There is no automatic <EOL>
514detection, because it's common to start with a line that defines a mapping
515that ends in a <CR>, which will confuse the automaton.
516
517 *line-continuation*
518Long lines in a ":source"d Ex command script file can be split by inserting
519a line continuation symbol "\" (backslash) at the start of the next line.
520There can be white space before the backslash, which is ignored.
521
522Example: the lines >
523 :set comments=sr:/*,mb:*,el:*/,
524 \://,
525 \b:#,
526 \:%,
527 \n:>,
528 \fb:-
Milly89872f52024-10-05 17:16:18 +0200529are interpreted as if they were given in one line: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000530 :set comments=sr:/*,mb:*,el:*/,://,b:#,:%,n:>,fb:-
531
532All leading whitespace characters in the line before a backslash are ignored.
533Note however that trailing whitespace in the line before it cannot be
534inserted freely; it depends on the position where a command is split up
535whether additional whitespace is allowed or not.
536
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100537When a space is required it's best to put it right after the backslash. A
538space at the end of a line is hard to see and may be accidentally deleted. >
539 :syn match Comment
540 \ "very long regexp"
541 \ keepend
542
Bram Moolenaara4d131d2021-12-27 21:33:07 +0000543In |Vim9| script the backslash can often be omitted, but not always.
544See |vim9-line-continuation|.
545
Bram Moolenaar071d4272004-06-13 20:20:40 +0000546There is a problem with the ":append" and ":insert" commands: >
547 :1append
548 \asdf
549 .
550The backslash is seen as a line-continuation symbol, thus this results in the
551command: >
552 :1appendasdf
553 .
554To avoid this, add the 'C' flag to the 'cpoptions' option: >
555 :set cpo+=C
556 :1append
557 \asdf
558 .
559 :set cpo-=C
560
561Note that when the commands are inside a function, you need to add the 'C'
562flag when defining the function, it is not relevant when executing it. >
563 :set cpo+=C
564 :function Foo()
565 :1append
566 \asdf
567 .
568 :endfunction
569 :set cpo-=C
Bram Moolenaar67f8ab82018-09-11 22:37:29 +0200570<
571 *line-continuation-comment*
Bram Moolenaar95bafa22018-10-02 13:26:25 +0200572To add a comment in between the lines start with '"\ '. Notice the space
573after the backslash. Example: >
Bram Moolenaar67f8ab82018-09-11 22:37:29 +0200574 let array = [
575 "\ first entry comment
576 \ 'first',
577 "\ second entry comment
578 \ 'second',
579 \ ]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000580
581Rationale:
582 Most programs work with a trailing backslash to indicate line
583 continuation. Using this in Vim would cause incompatibility with Vi.
584 For example for this Vi mapping: >
585 :map xx asdf\
586< Therefore the unusual leading backslash is used.
587
Bram Moolenaar67f8ab82018-09-11 22:37:29 +0200588 Starting a comment in a continuation line results in all following
589 continuation lines to be part of the comment. Since it was like this
590 for a long time, when making it possible to add a comment halfway a
591 sequence of continuation lines, it was not possible to use \", since
592 that was a valid continuation line. Using '"\ ' comes closest, even
593 though it may look a bit weird. Requiring the space after the
594 backslash is to make it very unlikely this is a normal comment line.
595
Bram Moolenaar071d4272004-06-13 20:20:40 +0000596==============================================================================
Bram Moolenaarf6fee0e2016-02-21 23:02:49 +01005975. Using Vim packages *packages*
598
599A Vim package is a directory that contains one or more plugins. The
600advantages over normal plugins:
601- A package can be downloaded as an archive and unpacked in its own directory.
Bram Moolenaar5f148ec2016-03-07 22:59:26 +0100602 Thus the files are not mixed with files of other plugins. That makes it
603 easy to update and remove.
Bram Moolenaar91715872016-03-03 17:13:03 +0100604- A package can be a git, mercurial, etc. repository. That makes it really
Bram Moolenaarf6fee0e2016-02-21 23:02:49 +0100605 easy to update.
606- A package can contain multiple plugins that depend on each other.
607- A package can contain plugins that are automatically loaded on startup and
Bram Moolenaar5f148ec2016-03-07 22:59:26 +0100608 ones that are only loaded when needed with `:packadd`.
609
610
611Using a package and loading automatically ~
Bram Moolenaarf6fee0e2016-02-21 23:02:49 +0100612
613Let's assume your Vim files are in the "~/.vim" directory and you want to add a
Milly89872f52024-10-05 17:16:18 +0200614package from a zip archive "/tmp/foopack.zip": >
Bram Moolenaar5f148ec2016-03-07 22:59:26 +0100615 % mkdir -p ~/.vim/pack/foo
616 % cd ~/.vim/pack/foo
617 % unzip /tmp/foopack.zip
Bram Moolenaarf6fee0e2016-02-21 23:02:49 +0100618
Bram Moolenaar5f148ec2016-03-07 22:59:26 +0100619The directory name "foo" is arbitrary, you can pick anything you like.
Bram Moolenaarf6fee0e2016-02-21 23:02:49 +0100620
621You would now have these files under ~/.vim:
Bram Moolenaar5f148ec2016-03-07 22:59:26 +0100622 pack/foo/README.txt
Bram Moolenaaraf1a0e32016-03-09 22:19:26 +0100623 pack/foo/start/foobar/plugin/foo.vim
624 pack/foo/start/foobar/syntax/some.vim
Bram Moolenaar5f148ec2016-03-07 22:59:26 +0100625 pack/foo/opt/foodebug/plugin/debugger.vim
Bram Moolenaarf6fee0e2016-02-21 23:02:49 +0100626
Bram Moolenaar5f148ec2016-03-07 22:59:26 +0100627When Vim starts up, after processing your .vimrc, it scans all directories in
Bram Moolenaar03413f42016-04-12 21:07:15 +0200628'packpath' for plugins under the "pack/*/start" directory. First all those
629directories are added to 'runtimepath'. Then all the plugins are loaded.
630See |packload-two-steps| for how these two steps can be useful.
Bram Moolenaarf3654822016-03-04 22:12:23 +0100631
Bram Moolenaar3c053a12022-10-16 13:11:12 +0100632To allow for calling into package functionality while parsing your .vimrc,
633|:colorscheme| and |autoload| will both automatically search under 'packpath'
634as well in addition to 'runtimepath'. See the documentation for each for
635details.
636
Bram Moolenaar664f3cf2019-12-07 16:03:51 +0100637In the example Vim will find "pack/foo/start/foobar/plugin/foo.vim" and adds
Bram Moolenaaraf1a0e32016-03-09 22:19:26 +0100638"~/.vim/pack/foo/start/foobar" to 'runtimepath'.
Bram Moolenaarf6fee0e2016-02-21 23:02:49 +0100639
Bram Moolenaar5f148ec2016-03-07 22:59:26 +0100640If the "foobar" plugin kicks in and sets the 'filetype' to "some", Vim will
641find the syntax/some.vim file, because its directory is in 'runtimepath'.
Bram Moolenaarf6fee0e2016-02-21 23:02:49 +0100642
Bram Moolenaar5f148ec2016-03-07 22:59:26 +0100643Vim will also load ftdetect files, if there are any.
Bram Moolenaarf6fee0e2016-02-21 23:02:49 +0100644
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100645Note that the files under "pack/foo/opt" are not loaded automatically, only the
Bram Moolenaaraf1a0e32016-03-09 22:19:26 +0100646ones under "pack/foo/start". See |pack-add| below for how the "opt" directory
Bram Moolenaar5f148ec2016-03-07 22:59:26 +0100647is used.
Bram Moolenaarf6fee0e2016-02-21 23:02:49 +0100648
Bram Moolenaar8dcf2592016-03-12 22:47:14 +0100649Loading packages automatically will not happen if loading plugins is disabled,
650see |load-plugins|.
651
652To load packages earlier, so that 'runtimepath' gets updated: >
653 :packloadall
654This also works when loading plugins is disabled. The automatic loading will
655only happen once.
Bram Moolenaarf6fee0e2016-02-21 23:02:49 +0100656
Bram Moolenaar26852122016-05-24 20:02:38 +0200657If the package has an "after" directory, that directory is added to the end of
658'runtimepath', so that anything there will be loaded later.
659
Bram Moolenaar5f148ec2016-03-07 22:59:26 +0100660
661Using a single plugin and loading it automatically ~
662
663If you don't have a package but a single plugin, you need to create the extra
Milly89872f52024-10-05 17:16:18 +0200664directory level: >
Bram Moolenaaraf1a0e32016-03-09 22:19:26 +0100665 % mkdir -p ~/.vim/pack/foo/start/foobar
666 % cd ~/.vim/pack/foo/start/foobar
Bram Moolenaar5f148ec2016-03-07 22:59:26 +0100667 % unzip /tmp/someplugin.zip
668
669You would now have these files:
Bram Moolenaaraf1a0e32016-03-09 22:19:26 +0100670 pack/foo/start/foobar/plugin/foo.vim
671 pack/foo/start/foobar/syntax/some.vim
Bram Moolenaar5f148ec2016-03-07 22:59:26 +0100672
673From here it works like above.
674
675
676Optional plugins ~
677 *pack-add*
678To load an optional plugin from a pack use the `:packadd` command: >
679 :packadd foodebug
680This searches for "pack/*/opt/foodebug" in 'packpath' and will find
681~/.vim/pack/foo/opt/foodebug/plugin/debugger.vim and source it.
682
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100683This could be done if some conditions are met. For example, depending on
684whether Vim supports a feature or a dependency is missing.
685
686You can also load an optional plugin at startup, by putting this command in
687your |.vimrc|: >
688 :packadd! foodebug
Bram Moolenaarc95a3022016-06-12 23:01:46 +0200689The extra "!" is so that the plugin isn't loaded if Vim was started with
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100690|--noplugin|.
Bram Moolenaar5f148ec2016-03-07 22:59:26 +0100691
692It is perfectly normal for a package to only have files in the "opt"
693directory. You then need to load each plugin when you want to use it.
694
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100695
696Where to put what ~
697
698Since color schemes, loaded with `:colorscheme`, are found below
699"pack/*/start" and "pack/*/opt", you could put them anywhere. We recommend
700you put them below "pack/*/opt", for example
701".vim/pack/mycolors/opt/dark/colors/very_dark.vim".
702
703Filetype plugins should go under "pack/*/start", so that they are always
704found. Unless you have more than one plugin for a file type and want to
705select which one to load with `:packadd`. E.g. depending on the compiler
706version: >
707 if foo_compiler_version > 34
708 packadd foo_new
709 else
710 packadd foo_old
711 endif
712
713The "after" directory is most likely not useful in a package. It's not
714disallowed though.
715
Bram Moolenaarf6fee0e2016-02-21 23:02:49 +0100716==============================================================================
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01007176. Creating Vim packages *package-create*
718
719This assumes you write one or more plugins that you distribute as a package.
720
721If you have two unrelated plugins you would use two packages, so that Vim
Bram Moolenaar2547aa92020-07-26 17:00:44 +0200722users can choose what they include or not. Or you can decide to use one
Bram Moolenaar3d1cde82020-08-15 18:55:18 +0200723package with optional plugins, and tell the user to add the preferred ones with
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100724`:packadd`.
725
726Decide how you want to distribute the package. You can create an archive or
727you could use a repository. An archive can be used by more users, but is a
728bit harder to update to a new version. A repository can usually be kept
729up-to-date easily, but it requires a program like "git" to be available.
730You can do both, github can automatically create an archive for a release.
731
732Your directory layout would be like this:
Bram Moolenaar938ae282023-02-20 20:44:55 +0000733 start/foobar/plugin/foo.vim " always loaded, defines commands
734 start/foobar/plugin/bar.vim " always loaded, defines commands
735 start/foobar/autoload/foo.vim " loaded when foo command used
736 start/foobar/doc/foo.txt " help for foo.vim
737 start/foobar/doc/tags " help tags
RestorerZ96509102024-07-11 21:14:15 +0200738 start/foobar/lang/<lang_id>/LC_MESSAGES/foobar.mo
Christ van Willegence0ef912024-06-20 23:41:59 +0200739 " messages for the plugin in the
740 " <lang_id> language. These files are
741 " optional.
Bram Moolenaar938ae282023-02-20 20:44:55 +0000742 opt/fooextra/plugin/extra.vim " optional plugin, defines commands
743 opt/fooextra/autoload/extra.vim " loaded when extra command used
744 opt/fooextra/doc/extra.txt " help for extra.vim
745 opt/fooextra/doc/tags " help tags
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100746
747This allows for the user to do: >
Bram Moolenaarc8cdf0f2021-03-13 13:28:13 +0100748 mkdir ~/.vim/pack
749 cd ~/.vim/pack
750 git clone https://github.com/you/foobar.git myfoobar
RestorerZ96509102024-07-11 21:14:15 +0200751<
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100752Here "myfoobar" is a name that the user can choose, the only condition is that
753it differs from other packages.
754
755In your documentation you explain what the plugins do, and tell the user how
756to load the optional plugin: >
757 :packadd! fooextra
RestorerZ96509102024-07-11 21:14:15 +0200758<
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100759You could add this packadd command in one of your plugins, to be executed when
760the optional plugin is needed.
761
RestorerZ96509102024-07-11 21:14:15 +0200762 *package-doc* *package-documentation*
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100763Run the `:helptags` command to generate the doc/tags file. Including this
Bram Moolenaar3d1cde82020-08-15 18:55:18 +0200764generated file in the package means that the user can drop the package in the
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100765pack directory and the help command works right away. Don't forget to re-run
766the command after changing the plugin help: >
767 :helptags path/start/foobar/doc
768 :helptags path/opt/fooextra/doc
Christ van Willegence0ef912024-06-20 23:41:59 +0200769<
RestorerZ96509102024-07-11 21:14:15 +0200770 *package-translation*
771In order for a plugin to display translated messages, a few steps are
772required.
773The author of the plugin who likes to translate messages must define the name
774of the package and the location of the directory where the translations can be
775found using the |bindtextdomain()| function: >
776 :call bindtextdomain("foobar",
777 \ fnamemodify(expand("<script>"), ':p:h') .. '/../lang/')
Christ van Willegence0ef912024-06-20 23:41:59 +0200778<
RestorerZ96509102024-07-11 21:14:15 +0200779Where:
780 "foobar" is the unique package identifier by which the |gettext()|
781 function will later search for translation strings for this
782 plugin.
783 "lang/" is the relative or absolute path to the directory structure
784 where the translation file is located.
Christ van Willegence0ef912024-06-20 23:41:59 +0200785
RestorerZ96509102024-07-11 21:14:15 +0200786The directory structure where the message translation files should be placed
787is (from the top-level directory of the package):
788"lang/<lang_id>/LC_MESSAGES". For the format of <lang_id> see |multi-lang|.
789This function needs to be called only once during the initialization of the
790plugin.
791Once this is done, the |gettext()| function can be used to retrieve translated
792messages: >
793 :echo gettext("Hello", "foobar")
Christ van Willegence0ef912024-06-20 23:41:59 +0200794<
RestorerZ96509102024-07-11 21:14:15 +0200795Where:
h-east90e1fe42024-08-12 18:26:08 +0200796 "Hello" the message "Hello" to be translated into the user's language
797 |:lang|
RestorerZ96509102024-07-11 21:14:15 +0200798 "foobar" the package identifier, which was previously defined using the
799 |bindtextdomain()| function.
800
801After that you need to create a template file for translation - POT-file.
802To do this, execute the following commands (using the Vim repository): >
803 cd ~/forkvim/src/po
804 make -f Makefile "PLUGPACKAGE={package}" \
805 "PO_PLUG_INPUTLIST={path/to/scripts-that-need-translations.vim}" \
806 ["POT_PLUGPACKAGE_PATH={path/where/to/write/{package}.pot}" \]
807 ["VIMPROG={path/to/vim} \]
808 {package}.pot
809<
810Where:
811PLUGPACKAGE A variable containing the name of the package that we
812 specified in the |bindtextdomain()| and
813 |gettext()| functions, for example, "foobar".
814PO_PLUG_INPUTLIST A variable containing scripts that have strings
815 to translate, i.e. where we specified the |gettext()|
816 function. Scripts are specified with an absolute
817 or relative path. Example: start/foobar/plugin/bar.vim
818 use blanks to separate scripts.
819POT_PLUGPACKAGE_PATH A variable containing the directory where the prepared
820 POT file will be saved. This is not a required variable,
821 if no directory is specified, then the POT file will
822 be placed in the "src/po" directory.
823VIMPROG A variable containing a directory with a working Vim.
824 If the Vim editor is already built and installed, and
825 is contained in the $PATH environment variable,
826 then you can specify just the name of the vim
827 executable.
828{package}.pot This is the Target. It is specified as the name of
829 the package, for example, "foobar" with the addition
830 of the .pot extension.
831Once a POT file is created, its contents are copied into separate PO files for
832each language for which the translation will be prepared.
833
834When the translation is finished, it is necessary to convert the PO files into
835binary MO-files format and place these MO-files into the "lang/" directory, the
836structure of which we created earlier.
837To do this, run the following commands:
838>
839 cd ~/forkvim/src/po
840 make -f Makefile "PLUGPACKAGE={package}" \
841 "PO_PLUGPACKAGE={path/to/{lang}.po}" \
842 ["MO_PLUGPACKAGE_PATH={path/to/lang/<lang_id>/LC_MESSAGES}" \]
843 {package}.mo
844<
845Where:
846PLUGPACKAGE A variable containing the name of the package that we
847 specified in the |bindtextdomain()| and |gettext()|
848 functions, for example, "foobar".
849PO_PLUGPACKAGE A variable containing a PO file. The file is specified
850 with an absolute or relative path. For example,
851 "~/myproject/translate/en.po"
852MO_PLUGPACKAGE_PATH A variable containing the structure of the "lang/"
853 directory, where the file with translations will be
854 placed, for example, "foobar.mo". This is not
855 a required variable, if the directory is not specified,
856 the MO file will be saved in the "src/po" directory.
857{package}.mo This is the Target. It is specified as the name of
858 the package, for example, "foobar" with the addition
859 of the .mo extension.
860
861 *package-translate_example*
862Let's show it all on some concrete example and translate the
863"ftplugin/aap.vim" file into Russian and German.
864
865First, let's prepare the "aap.vim" file, specifying |bindtextdomain()| and
866|gettext()| function calls in it.
867>
868 " Only do this when not done yet for this buffer
869 if exists("b:did_ftplugin")
870 finish
871 endif
872
873 " Don't load another plugin for this buffer
874 let b:did_ftplugin = 1
875 call bindtextdomain("aap", fnamemodify(expand("<script>"), ':p:h') .. '/../lang/')
876
877 " Reset 'formatoptions', 'comments', 'commentstring' and 'expandtab' to undo
878 " this plugin.
879 let b:undo_ftplugin = "setl fo< com< cms< et<"
880
881 " Set 'formatoptions' to break comment lines but not other lines,
882 " and insert the comment leader when hitting <CR> or using "o".
883 setlocal fo-=t fo+=croql
884
885 " Set 'comments' to format dashed lists in comments.
886 setlocal comments=s:#\ -,m:#\ \ ,e:#,n:#,fb:-
887 setlocal commentstring=#\ %s
888
889 " Expand tabs to spaces to avoid trouble.
890 setlocal expandtab
891
892 if (has("gui_win32") || has("gui_gtk")) && !exists("b:browsefilter")
893 let b:browsefilter = gettext("Aap Recipe Files (*.aap)\t*.aap\n", "aap")
894 if has("win32")
895 let b:browsefilter ..= gettext("All Files (*.*)\t*\n", "aap")
896 else
897 let b:browsefilter ..= gettext("All Files (*)\t*\n", "aap")
898 endif
899 let b:undo_ftplugin ..= " | unlet! b:browsefilter"
900 endif
901<
902Now let's create a POT file for it (example uses Windows paths):
903>
904 cd /d f:\forkvim\src\po
905 (the following command must be entered in one line, here it is separated for example)
906 nmake.exe -f Make_mvc.mak "PLUGPACKAGE=aap"
907 "PO_PLUG_INPUTLIST=d:\Programs\vim\vim91\ftplugin\aap.vim"
908 "POT_PLUGPACKAGE_PATH=e:\project\translate\plugins"
909 "VIMPROG=d:\Programs\vim\vim91\vim.exe"
910 aap.pot
911<
912After the POT file of our package is created, go to the directory where we
913saved it and perform the translation.
914>
915 cd /d e:\project\translate\plugins
916 copy aap.pot ru.po
917 copy aap.pot de.po
918<
919We have prepared a PO file with a translation into Russian:
920 # Test plugins translate ~
921 # ~
922 msgid "" ~
923 msgstr "" ~
924 "Project-Id-Version: aap\n" ~
925 "Report-Msgid-Bugs-To: \n" ~
926 "POT-Creation-Date: 2024-06-23 14:58+0300\n" ~
927 "PO-Revision-Date: 2024-06-23 14:58+0300\n" ~
928 "Last-Translator: Restorer\n" ~
929 "Language-Team: RuVim\n" ~
930 "Language: ru\n" ~
931 "MIME-Version: 1.0\n" ~
932 "Content-Type: text/plain; charset=UTF-8\n" ~
933 "Content-Transfer-Encoding: 8bit\n" ~
934
935 #: ../../runtime/ftplugin/aap.vim:32 ~
936 msgid "Aap Recipe Files (*.aap)\t*.aap\n" ~
937 msgstr "Файлы инструкций Aap (*.aap)\t*.aap\n" ~
938
939 #: ../../runtime/ftplugin/aap.vim:34 ~
940 msgid "All Files (*.*)\t*\n" ~
941 msgstr "Все файлы (*.*)\t*\n" ~
942
943 #: ../../runtime/ftplugin/aap.vim:36 ~
944 msgid "All Files (*)\t*\n" ~
945 msgstr "Все файлы (*)\t*\n" ~
946
947And the PO file in German:
948 # Test plugins translate~
949 #~
950 msgid ""~
951 msgstr ""~
952 "Project-Id-Version: aap\n"~
953 "Report-Msgid-Bugs-To: \n"~
954 "POT-Creation-Date: 2024-06-23 14:58+0300\n"~
955 "PO-Revision-Date: 2024-06-24 13:11+0300\n"~
956 "Last-Translator: Restorer\n"~
957 "Language-Team: German\n"~
958 "Language: de\n"~
959 "MIME-Version: 1.0\n"~
960 "Content-Type: text/plain; charset=UTF-8\n"~
961 "Content-Transfer-Encoding: 8bit\n"~
962
963 #: ../../runtime/ftplugin/aap.vim:32~
964 msgid "Aap Recipe Files (*.aap)\t*.aap\n"~
965 msgstr "Aap-Rezeptdateien (*.aap)\t*.aap\n"~
966
967 #: ../../runtime/ftplugin/aap.vim:34~
968 msgid "All Files (*.*)\t*\n"~
969 msgstr "Alle Dateien (*.*)\t*.*\n"~
970
971 #: ../../runtime/ftplugin/aap.vim:36~
972 msgid "All Files (*)\t*\n"~
973 msgstr "Alle Dateien (*)\t*\n"~
974
975Now convert these files into MO files so that |gettext()| can display message
976translations. Note that since this is not a specialized plugin package, we
977will put the MO files in the "lang/" directory of the Vim editor.
978Type the following commands:
979>
980 cd /d f:\forkvim\src\po
Milly89872f52024-10-05 17:16:18 +0200981< (the following command must be entered in one line, here it is separated for example)
982 For Russian: >
RestorerZ96509102024-07-11 21:14:15 +0200983 nmake.exe -f Make_mvc.mak "PLUGPACKAGE=aap"
984 "PO_PLUGPACKAGE=e:\project\translate\plugins\ru.po"
985 "MO_PLUGPACKAGE_PATH=d:\Programs\vim\vim91\lang\ru\LC_MESSAGES"
986 aap.mo
Milly89872f52024-10-05 17:16:18 +0200987< For German: >
RestorerZ96509102024-07-11 21:14:15 +0200988 nmake.exe -f Make_mvc.mak "PLUGPACKAGE=aap"
989 "PO_PLUGPACKAGE=e:\project\translate\plugins\de.po"
990 "MO_PLUGPACKAGE_PATH=d:\Programs\vim\vim91\lang\de\LC_MESSAGES"
991 aap.mo
992<
993That's it, the translations are ready and you can see the plugin's messages
994in your native language.
995
996Let's also try to translate a plugin package. For example, when a package
997contains several scripts containing strings that need to be translated.
998For example, let's translate the "netrw" package into Japanese.
999For this example, we will translate only a few lines from this package.
1000Let's prepare the scripts where we need to translate the message strings.
1001
1002The file "autoload\netrw.vim":
1003>
1004 " Load Once:
1005 if &cp || exists("g:loaded_netrw")
1006 finish
1007 endif
1008 call bindtextdomain("netrw", fnamemodify(expand("<script>"), ':p:h') .. '/../lang/')
1009
1010 " Check that vim has patches that netrw requires.
1011 " Patches needed for v7.4: 1557, and 213.
1012 " (netrw will benefit from vim's having patch#656, too)
1013 let s:needspatches=[1557,213]
1014 if exists("s:needspatches")
1015 for ptch in s:needspatches
1016 if v:version < 704 || (v:version == 704 && !has("patch".ptch))
1017 if !exists("s:needpatch{ptch}")
1018 unsilent echomsg gettext("***sorry*** this version of netrw requires vim v7.4 with patch#", "netrw") .. ptch
1019 endif
1020 let s:needpatch{ptch}= 1
1021 finish
1022 endif
1023 endfor
1024 endif
1025<
1026The file "autoload\netrwSettings.vim":
1027>
1028 " Load Once:
1029 if exists("g:loaded_netrwSettings") || &cp
1030 finish
1031 endif
1032 call bindtextdomain("netrw", fnamemodify(expand("<script>"), ':p:h') .. '/../lang/')
1033 let g:loaded_netrwSettings = "v18"
1034 if v:version < 700
1035 echohl WarningMsg
1036 echo gettext("***warning*** this version of netrwSettings needs vim 7.0", "netrw")
1037 echohl Normal
1038 finish
1039 endif
1040<
1041Now we will prepare a POT file for further translation of messages.
1042Execute the following commands:
1043>
1044 cd ~/forkvim/src/po
1045 make -f Makefile "VIMPROG=/usr/local/bin/vim" "PLUGPACKAGE=netrw" \
1046 "POT_PLUGPACKAGE_PATH=~/project/translate/plugins" \
1047 "PO_PLUG_INPUTLIST=../../runtime/autoload/netrw.vim
1048 ../../runtime/autoload/netrwSettings.vim" \
1049 netrw.pot
1050<
1051Go to the directory with the POT file and make the translation:
1052>
1053 cd ~/project/translate/plugins
1054 cp ./netrw.pot ja.po
1055<
1056When we have the translation ready in the "ja.po" file:
1057 # Test plugins translate ~
1058 # ~
1059 msgid "" ~
1060 msgstr "" ~
1061 "Project-Id-Version: netrw\n" ~
1062 "Report-Msgid-Bugs-To: \n" ~
1063 "POT-Creation-Date: 2024-06-23 17:14+0300\n" ~
1064 "PO-Revision-Date: 2024-06-23 17:14+0300\n" ~
1065 "Last-Translator: Restorer\n" ~
1066 "Language-Team: Japanese\n" ~
1067 "Language: ja\n" ~
1068 "MIME-Version: 1.0\n" ~
1069 "Content-Type: text/plain; charset=UTF-8\n" ~
1070 "Content-Transfer-Encoding: 8bit\n" ~
1071
1072 #: ../../runtime/autoload/netrw.vim:51 ~
1073 msgid "***sorry*** this version of netrw requires vim v7.4 with patch#" ~
1074 msgstr "" ~
1075 "***申し訳ありません***このバージョンのnetrwには、パッチ付きのvim v7.4が必要です#" ~
1076
1077 #: ../../runtime/autoload/netrwSettings.vim:28 ~
1078 msgid "***warning*** this version of netrwSettings needs vim 7.0" ~
1079 msgstr "***警告***このバージョンのnetrwSettingsにはvim7.0が必要です" ~
1080
1081Convert ja.po to a MO file:
1082>
1083 cd ~/forkvim/src/po
1084 make -f Makefile "PLUGPACKAGE=netrw" \
1085 "PO_PLUGPACKAGE=~/project/translate/plugins/ja.po" \
1086 "MO_PLUGPACKAGE_PATH=/usr/local/share/vim/vim91/lang/ja/LC_MESSAGES" \
1087 netrw.mo
1088<
1089Executing those steps will allow you to get translation of any third-party
1090plug-in packages.
Bram Moolenaar03413f42016-04-12 21:07:15 +02001091
1092Dependencies between plugins ~
1093 *packload-two-steps*
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001094Suppose you have two plugins that depend on the same functionality. You can
Bram Moolenaar03413f42016-04-12 21:07:15 +02001095put the common functionality in an autoload directory, so that it will be
1096found automatically. Your package would have these files:
1097
1098 pack/foo/start/one/plugin/one.vim >
1099 call foolib#getit()
1100< pack/foo/start/two/plugin/two.vim >
1101 call foolib#getit()
1102< pack/foo/start/lib/autoload/foolib.vim >
1103 func foolib#getit()
1104
1105This works, because loading packages will first add all found directories to
1106'runtimepath' before sourcing the plugins.
1107
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01001108==============================================================================
11097. Debugging scripts *debug-scripts*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001110
1111Besides the obvious messages that you can add to your scripts to find out what
1112they are doing, Vim offers a debug mode. This allows you to step through a
1113sourced file or user function and set breakpoints.
1114
1115NOTE: The debugging mode is far from perfect. Debugging will have side
1116effects on how Vim works. You cannot use it to debug everything. For
1117example, the display is messed up by the debugging messages.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001118
1119An alternative to debug mode is setting the 'verbose' option. With a bigger
1120number it will give more verbose messages about what Vim is doing.
1121
1122
1123STARTING DEBUG MODE *debug-mode*
1124
1125To enter debugging mode use one of these methods:
11261. Start Vim with the |-D| argument: >
1127 vim -D file.txt
1128< Debugging will start as soon as the first vimrc file is sourced. This is
1129 useful to find out what is happening when Vim is starting up. A side
1130 effect is that Vim will switch the terminal mode before initialisations
1131 have finished, with unpredictable results.
1132 For a GUI-only version (Windows, Macintosh) the debugging will start as
1133 soon as the GUI window has been opened. To make this happen early, add a
1134 ":gui" command in the vimrc file.
1135 *:debug*
11362. Run a command with ":debug" prepended. Debugging will only be done while
1137 this command executes. Useful for debugging a specific script or user
1138 function. And for scripts and functions used by autocommands. Example: >
1139 :debug edit test.txt.gz
1140
11413. Set a breakpoint in a sourced file or user function. You could do this in
1142 the command line: >
1143 vim -c "breakadd file */explorer.vim" .
1144< This will run Vim and stop in the first line of the "explorer.vim" script.
1145 Breakpoints can also be set while in debugging mode.
1146
1147In debugging mode every executed command is displayed before it is executed.
1148Comment lines, empty lines and lines that are not executed are skipped. When
1149a line contains two commands, separated by "|", each command will be displayed
1150separately.
1151
1152
1153DEBUG MODE
1154
1155Once in debugging mode, the usual Ex commands can be used. For example, to
1156inspect the value of a variable: >
1157 echo idx
1158When inside a user function, this will print the value of the local variable
1159"idx". Prepend "g:" to get the value of a global variable: >
1160 echo g:idx
1161All commands are executed in the context of the current function or script.
1162You can also set options, for example setting or resetting 'verbose' will show
1163what happens, but you might want to set it just before executing the lines you
1164are interested in: >
1165 :set verbose=20
1166
1167Commands that require updating the screen should be avoided, because their
1168effect won't be noticed until after leaving debug mode. For example: >
1169 :help
1170won't be very helpful.
1171
1172There is a separate command-line history for debug mode.
1173
Bram Moolenaar6304be62021-11-27 10:57:26 +00001174NOTE: In Vim9 script, if a command is written at the script level and
1175continues on the next line, not using the old way with a backslash for line
1176continuation, only the first line is printed before the debugging prompt.
1177
Bram Moolenaar071d4272004-06-13 20:20:40 +00001178The line number for a function line is relative to the start of the function.
1179If you have trouble figuring out where you are, edit the file that defines
1180the function in another Vim, search for the start of the function and do
1181"99j". Replace "99" with the line number.
1182
1183Additionally, these commands can be used:
1184 *>cont*
1185 cont Continue execution until the next breakpoint is hit.
1186 *>quit*
1187 quit Abort execution. This is like using CTRL-C, some
1188 things might still be executed, doesn't abort
1189 everything. Still stops at the next breakpoint.
1190 *>next*
1191 next Execute the command and come back to debug mode when
1192 it's finished. This steps over user function calls
1193 and sourced files.
1194 *>step*
1195 step Execute the command and come back to debug mode for
1196 the next command. This steps into called user
1197 functions and sourced files.
1198 *>interrupt*
1199 interrupt This is like using CTRL-C, but unlike ">quit" comes
1200 back to debug mode for the next command that is
1201 executed. Useful for testing |:finally| and |:catch|
1202 on interrupt exceptions.
1203 *>finish*
1204 finish Finish the current script or user function and come
1205 back to debug mode for the command after the one that
1206 sourced or called it.
Bram Moolenaarf1f60f82016-01-16 15:40:53 +01001207 *>bt*
1208 *>backtrace*
1209 *>where*
1210 backtrace Show the call stacktrace for current debugging session.
1211 bt
1212 where
1213 *>frame*
Bram Moolenaar38a55632016-02-15 22:07:32 +01001214 frame N Goes to N backtrace level. + and - signs make movement
Bram Moolenaarf1f60f82016-01-16 15:40:53 +01001215 relative. E.g., ":frame +3" goes three frames up.
1216 *>up*
1217 up Goes one level up from call stacktrace.
1218 *>down*
1219 down Goes one level down from call stacktrace.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001220
1221About the additional commands in debug mode:
1222- There is no command-line completion for them, you get the completion for the
1223 normal Ex commands only.
Bram Moolenaardae8d212016-02-27 22:40:16 +01001224- You can shorten them, up to a single character, unless more than one command
Bram Moolenaarf1f60f82016-01-16 15:40:53 +01001225 starts with the same letter. "f" stands for "finish", use "fr" for "frame".
Bram Moolenaar071d4272004-06-13 20:20:40 +00001226- Hitting <CR> will repeat the previous one. When doing another command, this
1227 is reset (because it's not clear what you want to repeat).
1228- When you want to use the Ex command with the same name, prepend a colon:
1229 ":cont", ":next", ":finish" (or shorter).
Bram Moolenaar4d8f4762021-06-27 15:18:56 +02001230 *vim9-debug*
1231When debugging a compiled :def function, "step" will stop before every
Bram Moolenaar90df4b92021-07-07 20:26:08 +02001232executed line, not every single instruction. Thus it works mostly like a not
Bram Moolenaar4d8f4762021-06-27 15:18:56 +02001233compiled function. Access to local variables is limited you can use: >
1234 echo varname
1235But not much else.
1236When executing a command that is not a specific bytecode instruction but
1237executed like a normal Ex command, "step" will stop once in the compiled
1238context, where local variables can be inspected, and once just before
1239executing the command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001240
Bram Moolenaar9fbdbb82022-09-27 17:30:34 +01001241In a :def function variables that haven't been declared yet cannot be
1242inspected. Variables that have been declared can be inspected, also when the
1243block they were declared in has finished. In commands this would not be
1244possible, thus is slightly misleading (but can be useful).
1245
Bram Moolenaarf1f60f82016-01-16 15:40:53 +01001246The backtrace shows the hierarchy of function calls, e.g.:
1247 >bt ~
1248 3 function One[3] ~
1249 2 Two[3] ~
1250 ->1 Three[3] ~
1251 0 Four ~
1252 line 1: let four = 4 ~
1253
1254The "->" points to the current frame. Use "up", "down" and "frame N" to
1255select another frame.
1256
1257In the current frame you can evaluate the local function variables. There is
1258no way to see the command at the current line yet.
1259
Bram Moolenaar071d4272004-06-13 20:20:40 +00001260
1261DEFINING BREAKPOINTS
1262 *:breaka* *:breakadd*
1263:breaka[dd] func [lnum] {name}
1264 Set a breakpoint in a function. Example: >
1265 :breakadd func Explore
1266< Doesn't check for a valid function name, thus the breakpoint
1267 can be set before the function is defined.
1268
1269:breaka[dd] file [lnum] {name}
1270 Set a breakpoint in a sourced file. Example: >
1271 :breakadd file 43 .vimrc
1272
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00001273:breaka[dd] here
1274 Set a breakpoint in the current line of the current file.
1275 Like doing: >
1276 :breakadd file <cursor-line> <current-file>
1277< Note that this only works for commands that are executed when
1278 sourcing the file, not for a function defined in that file.
1279
Bram Moolenaarc6f9f732018-02-11 19:06:26 +01001280:breaka[dd] expr {expression}
1281 Sets a breakpoint, that will break whenever the {expression}
1282 evaluates to a different value. Example: >
1283 :breakadd expr g:lnum
Bram Moolenaarc6f9f732018-02-11 19:06:26 +01001284< Will break, whenever the global variable lnum changes.
Bram Moolenaar6c391a72021-09-09 21:55:11 +02001285
1286 Errors in evaluation are suppressed, you can use the name of a
1287 variable that does not exist yet. This also means you will
1288 not notice anything if the expression has a mistake.
1289
Bram Moolenaarc6f9f732018-02-11 19:06:26 +01001290 Note if you watch a |script-variable| this will break
1291 when switching scripts, since the script variable is only
1292 valid in the script where it has been defined and if that
1293 script is called from several other scripts, this will stop
1294 whenever that particular variable will become visible or
Bram Moolenaar9faec4e2021-02-27 16:38:07 +01001295 inaccessible again.
Bram Moolenaarc6f9f732018-02-11 19:06:26 +01001296
Bram Moolenaar071d4272004-06-13 20:20:40 +00001297The [lnum] is the line number of the breakpoint. Vim will stop at or after
1298this line. When omitted line 1 is used.
1299
Bram Moolenaar05159a02005-02-26 23:04:13 +00001300 *:debug-name*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001301{name} is a pattern that is matched with the file or function name. The
1302pattern is like what is used for autocommands. There must be a full match (as
1303if the pattern starts with "^" and ends in "$"). A "*" matches any sequence
1304of characters. 'ignorecase' is not used, but "\c" can be used in the pattern
1305to ignore case |/\c|. Don't include the () for the function name!
1306
Bram Moolenaar843ee412004-06-30 16:16:41 +00001307The match for sourced scripts is done against the full file name. If no path
1308is specified the current directory is used. Examples: >
1309 breakadd file explorer.vim
1310matches "explorer.vim" in the current directory. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001311 breakadd file *explorer.vim
Bram Moolenaar843ee412004-06-30 16:16:41 +00001312matches ".../plugin/explorer.vim", ".../plugin/iexplorer.vim", etc. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001313 breakadd file */explorer.vim
Bram Moolenaar843ee412004-06-30 16:16:41 +00001314matches ".../plugin/explorer.vim" and "explorer.vim" in any other directory.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001315
1316The match for functions is done against the name as it's shown in the output
Bram Moolenaarb2049902021-01-24 12:53:53 +01001317of ":function". However, for local functions the script-specific prefix such
1318as "<SNR>99_" is ignored to make it easier to match script-local functions
1319without knowing the ID of the script.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001320
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00001321Note that functions are first loaded and later executed. When they are loaded
1322the "file" breakpoints are checked, when they are executed the "func"
1323breakpoints.
1324
Bram Moolenaar071d4272004-06-13 20:20:40 +00001325
1326DELETING BREAKPOINTS
1327 *:breakd* *:breakdel* *E161*
1328:breakd[el] {nr}
1329 Delete breakpoint {nr}. Use |:breaklist| to see the number of
1330 each breakpoint.
1331
Bram Moolenaarf461c8e2005-06-25 23:04:51 +00001332:breakd[el] *
1333 Delete all breakpoints.
1334
Bram Moolenaar071d4272004-06-13 20:20:40 +00001335:breakd[el] func [lnum] {name}
1336 Delete a breakpoint in a function.
1337
1338:breakd[el] file [lnum] {name}
1339 Delete a breakpoint in a sourced file.
1340
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00001341:breakd[el] here
1342 Delete a breakpoint at the current line of the current file.
1343
Bram Moolenaar071d4272004-06-13 20:20:40 +00001344When [lnum] is omitted, the first breakpoint in the function or file is
1345deleted.
1346The {name} must be exactly the same as what was typed for the ":breakadd"
1347command. "explorer", "*explorer.vim" and "*explorer*" are different.
1348
1349
1350LISTING BREAKPOINTS
1351 *:breakl* *:breaklist*
1352:breakl[ist]
1353 List all breakpoints.
1354
1355
1356OBSCURE
1357
1358 *:debugg* *:debuggreedy*
1359:debugg[reedy]
1360 Read debug mode commands from the normal input stream, instead
1361 of getting them directly from the user. Only useful for test
1362 scripts. Example: >
1363 echo 'q^Mq' | vim -e -s -c debuggreedy -c 'breakadd file script.vim' -S script.vim
1364
1365:0debugg[reedy]
1366 Undo ":debuggreedy": get debug mode commands directly from the
1367 user, don't use typeahead for debug commands.
1368
Bram Moolenaar05159a02005-02-26 23:04:13 +00001369==============================================================================
Bram Moolenaar4f3f6682016-03-26 23:01:59 +010013708. Profiling *profile* *profiling*
Bram Moolenaar05159a02005-02-26 23:04:13 +00001371
Bram Moolenaar996343d2010-07-04 22:20:21 +02001372Profiling means that Vim measures the time that is spent on executing
Bram Moolenaar05159a02005-02-26 23:04:13 +00001373functions and/or scripts. The |+profile| feature is required for this.
Bram Moolenaarb2049902021-01-24 12:53:53 +01001374It is included when Vim was compiled with "huge" features.
Bram Moolenaar05159a02005-02-26 23:04:13 +00001375
Bram Moolenaar433f7c82006-03-21 21:29:36 +00001376You can also use the |reltime()| function to measure time. This only requires
Bram Moolenaarb2049902021-01-24 12:53:53 +01001377the |+reltime| feature, which is present in more builds.
Bram Moolenaar433f7c82006-03-21 21:29:36 +00001378
Bram Moolenaar16ea3672013-07-28 16:02:18 +02001379For profiling syntax highlighting see |:syntime|.
1380
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +01001381For example, to profile the one_script.vim script file: >
1382 :profile start /tmp/one_script_profile
1383 :profile file one_script.vim
1384 :source one_script.vim
1385 :exit
1386
Bram Moolenaar16ea3672013-07-28 16:02:18 +02001387
Bram Moolenaar05159a02005-02-26 23:04:13 +00001388:prof[ile] start {fname} *:prof* *:profile* *E750*
Yegappan Lakshmanan18ee0f62022-04-08 13:23:19 +01001389 Start profiling, write the output in {fname} upon exit or when
1390 a `:profile stop` or `:profile dump` command is invoked.
Bram Moolenaar0a63ded2015-04-15 13:31:24 +02001391 "~/" and environment variables in {fname} will be expanded.
Bram Moolenaar9b2200a2006-03-20 21:55:45 +00001392 If {fname} already exists it will be silently overwritten.
Bram Moolenaar05159a02005-02-26 23:04:13 +00001393 The variable |v:profiling| is set to one.
1394
Yegappan Lakshmanan18ee0f62022-04-08 13:23:19 +01001395:prof[ile] stop
1396 Write the collected profiling information to the logfile and
1397 stop profiling. You can use the `:profile start` command to
1398 clear the profiling statistics and start profiling again.
1399
Bram Moolenaar9b2200a2006-03-20 21:55:45 +00001400:prof[ile] pause
Christian Brabandt4bfb8992024-10-16 21:58:17 +02001401 Stop profiling until the next `:profile continue` command.
1402 Can be used when doing something that should not be counted
1403 (e.g., an external command). Does not nest.
Bram Moolenaar9b2200a2006-03-20 21:55:45 +00001404
1405:prof[ile] continue
Yegappan Lakshmanan18ee0f62022-04-08 13:23:19 +01001406 Continue profiling after `:profile pause`.
Bram Moolenaar9b2200a2006-03-20 21:55:45 +00001407
Bram Moolenaar05159a02005-02-26 23:04:13 +00001408:prof[ile] func {pattern}
1409 Profile function that matches the pattern {pattern}.
1410 See |:debug-name| for how {pattern} is used.
1411
1412:prof[ile][!] file {pattern}
1413 Profile script file that matches the pattern {pattern}.
1414 See |:debug-name| for how {pattern} is used.
1415 This only profiles the script itself, not the functions
1416 defined in it.
1417 When the [!] is added then all functions defined in the script
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +01001418 will also be profiled.
1419 Note that profiling only starts when the script is loaded
1420 after this command. A :profile command in the script itself
1421 won't work.
Bram Moolenaar05159a02005-02-26 23:04:13 +00001422
Yegappan Lakshmanan18ee0f62022-04-08 13:23:19 +01001423:prof[ile] dump
1424 Write the current state of profiling to the logfile
1425 immediately. After running this command, Vim continues to
1426 collect the profiling statistics.
Bram Moolenaar05159a02005-02-26 23:04:13 +00001427
Bram Moolenaard9fba312005-06-26 22:34:35 +00001428:profd[el] ... *:profd* *:profdel*
1429 Stop profiling for the arguments specified. See |:breakdel|
Yegappan Lakshmanan18ee0f62022-04-08 13:23:19 +01001430 for the arguments. Examples: >
1431 profdel func MyFunc
1432 profdel file MyScript.vim
1433 profdel here
Bram Moolenaard9fba312005-06-26 22:34:35 +00001434
Bram Moolenaar05159a02005-02-26 23:04:13 +00001435You must always start with a ":profile start fname" command. The resulting
Bram Moolenaarb2049902021-01-24 12:53:53 +01001436file is written when Vim exits. For example, to profile one specific
1437function: >
1438 profile start /tmp/vimprofile
1439 profile func MyFunc
1440
1441Here is an example of the output, with line
Bram Moolenaar05159a02005-02-26 23:04:13 +00001442numbers prepended for the explanation:
1443
1444 1 FUNCTION Test2() ~
1445 2 Called 1 time ~
1446 3 Total time: 0.155251 ~
1447 4 Self time: 0.002006 ~
1448 5 ~
1449 6 count total (s) self (s) ~
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001450 7 9 0.000096 for i in range(8) ~
1451 8 8 0.153655 0.000410 call Test3() ~
1452 9 8 0.000070 endfor ~
1453 10 " Ask a question ~
1454 11 1 0.001341 echo input("give me an answer: ") ~
Bram Moolenaar05159a02005-02-26 23:04:13 +00001455
1456The header (lines 1-4) gives the time for the whole function. The "Total"
1457time is the time passed while the function was executing. The "Self" time is
1458the "Total" time reduced by time spent in:
1459- other user defined functions
1460- sourced scripts
1461- executed autocommands
1462- external (shell) commands
1463
1464Lines 7-11 show the time spent in each executed line. Lines that are not
1465executed do not count. Thus a comment line is never counted.
1466
1467The Count column shows how many times a line was executed. Note that the
1468"for" command in line 7 is executed one more time as the following lines.
1469That is because the line is also executed to detect the end of the loop.
1470
1471The time Vim spends waiting for user input isn't counted at all. Thus how
1472long you take to respond to the input() prompt is irrelevant.
1473
1474Profiling should give a good indication of where time is spent, but keep in
1475mind there are various things that may clobber the results:
1476
Ernie Rael076de792023-03-16 21:43:15 +00001477- The accuracy of the time measured depends on the gettimeofday(), or
h_eastba77bbb2023-10-03 04:47:13 +09001478 clock_gettime() if available, system function. The accuracy ranges from
1479 1/100 second to nanoseconds. With clock_gettime() the times are displayed in
Bram Moolenaar71badf92023-04-22 22:40:14 +01001480 nanoseconds, otherwise microseconds. You can use `has("prof_nsec")`.
Bram Moolenaar05159a02005-02-26 23:04:13 +00001481
1482- Real elapsed time is measured, if other processes are busy they may cause
1483 delays at unpredictable moments. You may want to run the profiling several
1484 times and use the lowest results.
1485
1486- If you have several commands in one line you only get one time. Split the
1487 line to see the time for the individual commands.
1488
1489- The time of the lines added up is mostly less than the time of the whole
1490 function. There is some overhead in between.
1491
1492- Functions that are deleted before Vim exits will not produce profiling
1493 information. You can check the |v:profiling| variable if needed: >
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001494 :if !v:profiling
Bram Moolenaar05159a02005-02-26 23:04:13 +00001495 : delfunc MyFunc
1496 :endif
1497<
Bram Moolenaar8cd06ca2005-02-28 22:44:58 +00001498- Profiling may give weird results on multi-processor systems, when sleep
1499 mode kicks in or the processor frequency is reduced to save power.
Bram Moolenaar05159a02005-02-26 23:04:13 +00001500
Bram Moolenaarc81e5e72007-05-05 18:24:42 +00001501- The "self" time is wrong when a function is used recursively.
1502
1503
Bram Moolenaar91f84f62018-07-29 15:07:52 +02001504 vim:tw=78:ts=8:noet:ft=help:norl: