blob: 4a108b6ce189b33bc5cc0e49ce909a737832f236 [file] [log] [blame]
Bram Moolenaarc81e5e72007-05-05 18:24:42 +00001*repeat.txt* For Vim version 7.1a. Last change: 2007 Jan 07
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
111. Single repeats |single-repeat|
122. Multiple repeats |multi-repeat|
133. Complex repeats |complex-repeat|
144. Using Vim scripts |using-scripts|
155. Debugging scripts |debug-scripts|
Bram Moolenaar05159a02005-02-26 23:04:13 +0000166. Profiling |profiling|
Bram Moolenaar071d4272004-06-13 20:20:40 +000017
18==============================================================================
191. Single repeats *single-repeat*
20
21 *.*
22. Repeat last change, with count replaced with [count].
23 Also repeat a yank command, when the 'y' flag is
Bram Moolenaard4755bb2004-09-02 19:12:26 +000024 included in 'cpoptions'. Does not repeat a
25 command-line command.
Bram Moolenaar071d4272004-06-13 20:20:40 +000026
27Simple changes can be repeated with the "." command. Without a count, the
28count of the last change is used. If you enter a count, it will replace the
29last one. If the last change included a specification of a numbered register,
30the register number will be incremented. See |redo-register| for an example
31how to use this. Note that when repeating a command that used a Visual
32selection, the same SIZE of area is used, see |visual-repeat|.
33
34 *@:*
35@: Repeat last command-line [count] times.
36 {not available when compiled without the
37 |+cmdline_hist| feature}
38
39
40==============================================================================
412. Multiple repeats *multi-repeat*
42
43 *:g* *:global* *E147* *E148*
44:[range]g[lobal]/{pattern}/[cmd]
45 Execute the Ex command [cmd] (default ":p") on the
46 lines within [range] where {pattern} matches.
47
48:[range]g[lobal]!/{pattern}/[cmd]
49 Execute the Ex command [cmd] (default ":p") on the
50 lines within [range] where {pattern} does NOT match.
51
52 *:v* *:vglobal*
53:[range]v[global]/{pattern}/[cmd]
54 Same as :g!.
55
Bram Moolenaarc81e5e72007-05-05 18:24:42 +000056Instead of the '/' which surrounds the {pattern}, you can use any other
57single byte character, but not an alphanumeric character, '\', '"' or '|'.
58This is useful if you want to include a '/' in the search pattern or
59replacement string.
60
61For the definition of a pattern, see |pattern|.
62
Bram Moolenaar071d4272004-06-13 20:20:40 +000063The global commands work by first scanning through the [range] lines and
64marking each line where a match occurs (for a multi-line pattern, only the
65start of the match matters).
66In a second scan the [cmd] is executed for each marked line with its line
67number prepended. For ":v" and ":g!" the command is executed for each not
68marked line. If a line is deleted its mark disappears.
69The default for [range] is the whole buffer (1,$). Use "CTRL-C" to interrupt
70the command. If an error message is given for a line, the command for that
71line is aborted and the global command continues with the next marked or
72unmarked line.
73
74To repeat a non-Ex command, you can use the ":normal" command: >
75 :g/pat/normal {commands}
76Make sure that {commands} ends with a whole command, otherwise Vim will wait
77for you to type the rest of the command for each match. The screen will not
78have been updated, so you don't know what you are doing. See |:normal|.
79
80The undo/redo command will undo/redo the whole global command at once.
81The previous context mark will only be set once (with "''" you go back to
82where the cursor was before the global command).
83
84The global command sets both the last used search pattern and the last used
85substitute pattern (this is vi compatible). This makes it easy to globally
86replace a string:
87 :g/pat/s//PAT/g
88This replaces all occurrences of "pat" with "PAT". The same can be done with:
89 :%s/pat/PAT/g
90Which is two characters shorter!
91
Bram Moolenaar26a60b42005-02-22 08:49:11 +000092A special case is using ":visual" as a command. This will move to a matching
93line, go to Normal mode to let you execute commands there until you use |Q| to
94return to Ex mode. This will be repeated for each matching line. While doing
95this you cannot use ":global".
96
Bram Moolenaar071d4272004-06-13 20:20:40 +000097==============================================================================
983. Complex repeats *complex-repeat*
99
100 *q* *recording*
101q{0-9a-zA-Z"} Record typed characters into register {0-9a-zA-Z"}
102 (uppercase to append). The 'q' command is disabled
103 while executing a register, and it doesn't work inside
104 a mapping. {Vi: no recording}
105
106q Stops recording. (Implementation note: The 'q' that
107 stops recording is not stored in the register, unless
108 it was the result of a mapping) {Vi: no recording}
109
110 *@*
111@{0-9a-z".=*} Execute the contents of register {0-9a-z".=*} [count]
112 times. Note that register '%' (name of the current
113 file) and '#' (name of the alternate file) cannot be
114 used. For "@=" you are prompted to enter an
115 expression. The result of the expression is then
116 executed. See also |@:|. {Vi: only named registers}
117
Bram Moolenaar26a60b42005-02-22 08:49:11 +0000118 *@@* *E748*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000119@@ Repeat the previous @{0-9a-z":*} [count] times.
120
121:[addr]*{0-9a-z".=} *:@* *:star*
122:[addr]@{0-9a-z".=*} Execute the contents of register {0-9a-z".=*} as an Ex
123 command. First set cursor at line [addr] (default is
124 current line). When the last line in the register does
125 not have a <CR> it will be added automatically when
126 the 'e' flag is present in 'cpoptions'.
127 Note that the ":*" command is only recognized when the
128 '*' flag is present in 'cpoptions'. This is NOT the
129 default when 'nocompatible' is used.
130 For ":@=" the last used expression is used. The
131 result of evaluating the expression is executed as an
132 Ex command.
133 Mappings are not recognized in these commands.
134 {Vi: only in some versions} Future: Will execute the
135 register for each line in the address range.
136
137 *:@:*
138:[addr]@: Repeat last command-line. First set cursor at line
139 [addr] (default is current line). {not in Vi}
140
141 *:@@*
142:[addr]@@ Repeat the previous :@{0-9a-z"}. First set cursor at
143 line [addr] (default is current line). {Vi: only in
144 some versions}
145
146==============================================================================
1474. Using Vim scripts *using-scripts*
148
149For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|.
150
151 *:so* *:source* *load-vim-script*
152:so[urce] {file} Read Ex commands from {file}. These are commands that
153 start with a ":".
Bram Moolenaar1f35bf92006-03-07 22:38:47 +0000154 Triggers the |SourcePre| autocommand.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000155
156:so[urce]! {file} Read Vim commands from {file}. These are commands
157 that are executed from Normal mode, like you type
158 them.
159 When used after |:global|, |:argdo|, |:windo|,
160 |:bufdo|, in a loop or when another command follows
161 the display won't be updated while executing the
162 commands.
163 {not in Vi}
164
165 *:ru* *:runtime*
166:ru[ntime][!] {file} ..
167 Read Ex commands from {file} in each directory given
168 by 'runtimepath'. There is no error for non-existing
169 files. Example: >
170 :runtime syntax/c.vim
171
172< There can be multiple {file} arguments, separated by
173 spaces. Each {file} is searched for in the first
174 directory from 'runtimepath', then in the second
175 directory, etc. Use a backslash to include a space
176 inside {file} (although it's better not to use spaces
177 in file names, it causes trouble).
178
179 When [!] is included, all found files are sourced.
180 When it is not included only the first found file is
181 sourced.
182
183 When {file} contains wildcards it is expanded to all
184 matching files. Example: >
185 :runtime! plugin/*.vim
186< This is what Vim uses to load the plugin files when
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000187 starting up. This similar command: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000188 :runtime plugin/*.vim
189< would source the first file only.
190
191 When 'verbose' is one or higher, there is a message
192 when no file could be found.
193 When 'verbose' is two or higher, there is a message
194 about each searched file.
195 {not in Vi}
196
197:scripte[ncoding] [encoding] *:scripte* *:scriptencoding* *E167*
198 Specify the character encoding used in the script.
199 The following lines will be converted from [encoding]
200 to the value of the 'encoding' option, if they are
201 different. Examples: >
202 scriptencoding iso-8859-5
203 scriptencoding cp932
204<
205 When [encoding] is empty, no conversion is done. This
206 can be used to restrict conversion to a sequence of
207 lines: >
208 scriptencoding euc-jp
209 ... lines to be converted ...
210 scriptencoding
211 ... not converted ...
212
213< When conversion isn't supported by the system, there
214 is no error message and no conversion is done.
215
216 Don't use "ucs-2" or "ucs-4", scripts cannot be in
217 these encodings (they would contain NUL bytes).
218 When a sourced script starts with a BOM (Byte Order
219 Mark) in utf-8 format Vim will recognized it, no need
220 to use ":scriptencoding utf-8" then.
221
222 When compiled without the |+multi_byte| feature this
223 command is ignored.
224 {not in Vi}
225
226 *:scrip* *:scriptnames*
227:scrip[tnames] List all sourced script names, in the order they were
228 first sourced. The number is used for the script ID
229 |<SID>|.
230 {not in Vi} {not available when compiled without the
231 |+eval| feature}
232
233 *:fini* *:finish* *E168*
234:fini[sh] Stop sourcing a script. Can only be used in a Vim
235 script file. This is a quick way to skip the rest of
236 the file. If it is used after a |:try| but before the
237 matching |:finally| (if present), the commands
238 following the ":finally" up to the matching |:endtry|
239 are executed first. This process applies to all
240 nested ":try"s in the script. The outermost ":endtry"
241 then stops sourcing the script. {not in Vi}
242
243All commands and command sequences can be repeated by putting them in a named
244register and then executing it. There are two ways to get the commands in the
245register:
246- Use the record command "q". You type the commands once, and while they are
247 being executed they are stored in a register. Easy, because you can see
248 what you are doing. If you make a mistake, "p"ut the register into the
249 file, edit the command sequence, and then delete it into the register
250 again. You can continue recording by appending to the register (use an
251 uppercase letter).
252- Delete or yank the command sequence into the register.
253
254Often used command sequences can be put under a function key with the ':map'
255command.
256
257An alternative is to put the commands in a file, and execute them with the
258':source!' command. Useful for long command sequences. Can be combined with
259the ':map' command to put complicated commands under a function key.
260
261The ':source' command reads Ex commands from a file line by line. You will
262have to type any needed keyboard input. The ':source!' command reads from a
263script file character by character, interpreting each character as if you
264typed it.
265
266Example: When you give the ":!ls" command you get the |hit-enter| prompt. If
267you ':source' a file with the line "!ls" in it, you will have to type the
268<Enter> yourself. But if you ':source!' a file with the line ":!ls" in it,
269the next characters from that file are read until a <CR> is found. You will
270not have to type <CR> yourself, unless ":!ls" was the last line in the file.
271
272It is possible to put ':source[!]' commands in the script file, so you can
273make a top-down hierarchy of script files. The ':source' command can be
274nested as deep as the number of files that can be opened at one time (about
27515). The ':source!' command can be nested up to 15 levels deep.
276
277You can use the "<sfile>" string (literally, this is not a special key) inside
278of the sourced file, in places where a file name is expected. It will be
279replaced by the file name of the sourced file. For example, if you have a
280"other.vimrc" file in the same directory as your ".vimrc" file, you can source
281it from your ".vimrc" file with this command: >
282 :source <sfile>:h/other.vimrc
283
284In script files terminal-dependent key codes are represented by
285terminal-independent two character codes. This means that they can be used
286in the same way on different kinds of terminals. The first character of a
287key code is 0x80 or 128, shown on the screen as "~@". The second one can be
288found in the list |key-notation|. Any of these codes can also be entered
289with CTRL-V followed by the three digit decimal code. This does NOT work for
290the <t_xx> termcap codes, these can only be used in mappings.
291
292 *:source_crnl* *W15*
293MS-DOS, Win32 and OS/2: Files that are read with ":source" normally have
294<CR><NL> <EOL>s. These always work. If you are using a file with <NL> <EOL>s
295(for example, a file made on Unix), this will be recognized if 'fileformats'
296is not empty and the first line does not end in a <CR>. This fails if the
297first line has something like ":map <F1> :help^M", where "^M" is a <CR>. If
298the first line ends in a <CR>, but following ones don't, you will get an error
299message, because the <CR> from the first lines will be lost.
300
Bram Moolenaar520470a2005-06-16 21:59:56 +0000301Mac Classic: Files that are read with ":source" normally have <CR> <EOL>s.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000302These always work. If you are using a file with <NL> <EOL>s (for example, a
303file made on Unix), this will be recognized if 'fileformats' is not empty and
304the first line does not end in a <CR>. Be careful not to use a file with <NL>
305linebreaks which has a <CR> in first line.
306
307On other systems, Vim expects ":source"ed files to end in a <NL>. These
308always work. If you are using a file with <CR><NL> <EOL>s (for example, a
309file made on MS-DOS), all lines will have a trailing <CR>. This may cause
310problems for some commands (e.g., mappings). There is no automatic <EOL>
311detection, because it's common to start with a line that defines a mapping
312that ends in a <CR>, which will confuse the automaton.
313
314 *line-continuation*
315Long lines in a ":source"d Ex command script file can be split by inserting
316a line continuation symbol "\" (backslash) at the start of the next line.
317There can be white space before the backslash, which is ignored.
318
319Example: the lines >
320 :set comments=sr:/*,mb:*,el:*/,
321 \://,
322 \b:#,
323 \:%,
324 \n:>,
325 \fb:-
326are interpreted as if they were given in one line:
327 :set comments=sr:/*,mb:*,el:*/,://,b:#,:%,n:>,fb:-
328
329All leading whitespace characters in the line before a backslash are ignored.
330Note however that trailing whitespace in the line before it cannot be
331inserted freely; it depends on the position where a command is split up
332whether additional whitespace is allowed or not.
333
334There is a problem with the ":append" and ":insert" commands: >
335 :1append
336 \asdf
337 .
338The backslash is seen as a line-continuation symbol, thus this results in the
339command: >
340 :1appendasdf
341 .
342To avoid this, add the 'C' flag to the 'cpoptions' option: >
343 :set cpo+=C
344 :1append
345 \asdf
346 .
347 :set cpo-=C
348
349Note that when the commands are inside a function, you need to add the 'C'
350flag when defining the function, it is not relevant when executing it. >
351 :set cpo+=C
352 :function Foo()
353 :1append
354 \asdf
355 .
356 :endfunction
357 :set cpo-=C
358
359Rationale:
360 Most programs work with a trailing backslash to indicate line
361 continuation. Using this in Vim would cause incompatibility with Vi.
362 For example for this Vi mapping: >
363 :map xx asdf\
364< Therefore the unusual leading backslash is used.
365
366==============================================================================
3675. Debugging scripts *debug-scripts*
368
369Besides the obvious messages that you can add to your scripts to find out what
370they are doing, Vim offers a debug mode. This allows you to step through a
371sourced file or user function and set breakpoints.
372
373NOTE: The debugging mode is far from perfect. Debugging will have side
374effects on how Vim works. You cannot use it to debug everything. For
375example, the display is messed up by the debugging messages.
376{Vi does not have a debug mode}
377
378An alternative to debug mode is setting the 'verbose' option. With a bigger
379number it will give more verbose messages about what Vim is doing.
380
381
382STARTING DEBUG MODE *debug-mode*
383
384To enter debugging mode use one of these methods:
3851. Start Vim with the |-D| argument: >
386 vim -D file.txt
387< Debugging will start as soon as the first vimrc file is sourced. This is
388 useful to find out what is happening when Vim is starting up. A side
389 effect is that Vim will switch the terminal mode before initialisations
390 have finished, with unpredictable results.
391 For a GUI-only version (Windows, Macintosh) the debugging will start as
392 soon as the GUI window has been opened. To make this happen early, add a
393 ":gui" command in the vimrc file.
394 *:debug*
3952. Run a command with ":debug" prepended. Debugging will only be done while
396 this command executes. Useful for debugging a specific script or user
397 function. And for scripts and functions used by autocommands. Example: >
398 :debug edit test.txt.gz
399
4003. Set a breakpoint in a sourced file or user function. You could do this in
401 the command line: >
402 vim -c "breakadd file */explorer.vim" .
403< This will run Vim and stop in the first line of the "explorer.vim" script.
404 Breakpoints can also be set while in debugging mode.
405
406In debugging mode every executed command is displayed before it is executed.
407Comment lines, empty lines and lines that are not executed are skipped. When
408a line contains two commands, separated by "|", each command will be displayed
409separately.
410
411
412DEBUG MODE
413
414Once in debugging mode, the usual Ex commands can be used. For example, to
415inspect the value of a variable: >
416 echo idx
417When inside a user function, this will print the value of the local variable
418"idx". Prepend "g:" to get the value of a global variable: >
419 echo g:idx
420All commands are executed in the context of the current function or script.
421You can also set options, for example setting or resetting 'verbose' will show
422what happens, but you might want to set it just before executing the lines you
423are interested in: >
424 :set verbose=20
425
426Commands that require updating the screen should be avoided, because their
427effect won't be noticed until after leaving debug mode. For example: >
428 :help
429won't be very helpful.
430
431There is a separate command-line history for debug mode.
432
433The line number for a function line is relative to the start of the function.
434If you have trouble figuring out where you are, edit the file that defines
435the function in another Vim, search for the start of the function and do
436"99j". Replace "99" with the line number.
437
438Additionally, these commands can be used:
439 *>cont*
440 cont Continue execution until the next breakpoint is hit.
441 *>quit*
442 quit Abort execution. This is like using CTRL-C, some
443 things might still be executed, doesn't abort
444 everything. Still stops at the next breakpoint.
445 *>next*
446 next Execute the command and come back to debug mode when
447 it's finished. This steps over user function calls
448 and sourced files.
449 *>step*
450 step Execute the command and come back to debug mode for
451 the next command. This steps into called user
452 functions and sourced files.
453 *>interrupt*
454 interrupt This is like using CTRL-C, but unlike ">quit" comes
455 back to debug mode for the next command that is
456 executed. Useful for testing |:finally| and |:catch|
457 on interrupt exceptions.
458 *>finish*
459 finish Finish the current script or user function and come
460 back to debug mode for the command after the one that
461 sourced or called it.
462
463About the additional commands in debug mode:
464- There is no command-line completion for them, you get the completion for the
465 normal Ex commands only.
466- You can shorten them, up to a single character: "c", "n", "s" and "f".
467- Hitting <CR> will repeat the previous one. When doing another command, this
468 is reset (because it's not clear what you want to repeat).
469- When you want to use the Ex command with the same name, prepend a colon:
470 ":cont", ":next", ":finish" (or shorter).
471
472
473DEFINING BREAKPOINTS
474 *:breaka* *:breakadd*
475:breaka[dd] func [lnum] {name}
476 Set a breakpoint in a function. Example: >
477 :breakadd func Explore
478< Doesn't check for a valid function name, thus the breakpoint
479 can be set before the function is defined.
480
481:breaka[dd] file [lnum] {name}
482 Set a breakpoint in a sourced file. Example: >
483 :breakadd file 43 .vimrc
484
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000485:breaka[dd] here
486 Set a breakpoint in the current line of the current file.
487 Like doing: >
488 :breakadd file <cursor-line> <current-file>
489< Note that this only works for commands that are executed when
490 sourcing the file, not for a function defined in that file.
491
Bram Moolenaar071d4272004-06-13 20:20:40 +0000492The [lnum] is the line number of the breakpoint. Vim will stop at or after
493this line. When omitted line 1 is used.
494
Bram Moolenaar05159a02005-02-26 23:04:13 +0000495 *:debug-name*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000496{name} is a pattern that is matched with the file or function name. The
497pattern is like what is used for autocommands. There must be a full match (as
498if the pattern starts with "^" and ends in "$"). A "*" matches any sequence
499of characters. 'ignorecase' is not used, but "\c" can be used in the pattern
500to ignore case |/\c|. Don't include the () for the function name!
501
Bram Moolenaar843ee412004-06-30 16:16:41 +0000502The match for sourced scripts is done against the full file name. If no path
503is specified the current directory is used. Examples: >
504 breakadd file explorer.vim
505matches "explorer.vim" in the current directory. >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000506 breakadd file *explorer.vim
Bram Moolenaar843ee412004-06-30 16:16:41 +0000507matches ".../plugin/explorer.vim", ".../plugin/iexplorer.vim", etc. >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000508 breakadd file */explorer.vim
Bram Moolenaar843ee412004-06-30 16:16:41 +0000509matches ".../plugin/explorer.vim" and "explorer.vim" in any other directory.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000510
511The match for functions is done against the name as it's shown in the output
512of ":function". For local functions this means that something like "<SNR>99_"
513is prepended.
514
Bram Moolenaar2ce06f62005-01-31 19:19:04 +0000515Note that functions are first loaded and later executed. When they are loaded
516the "file" breakpoints are checked, when they are executed the "func"
517breakpoints.
518
Bram Moolenaar071d4272004-06-13 20:20:40 +0000519
520DELETING BREAKPOINTS
521 *:breakd* *:breakdel* *E161*
522:breakd[el] {nr}
523 Delete breakpoint {nr}. Use |:breaklist| to see the number of
524 each breakpoint.
525
Bram Moolenaarf461c8e2005-06-25 23:04:51 +0000526:breakd[el] *
527 Delete all breakpoints.
528
Bram Moolenaar071d4272004-06-13 20:20:40 +0000529:breakd[el] func [lnum] {name}
530 Delete a breakpoint in a function.
531
532:breakd[el] file [lnum] {name}
533 Delete a breakpoint in a sourced file.
534
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000535:breakd[el] here
536 Delete a breakpoint at the current line of the current file.
537
Bram Moolenaar071d4272004-06-13 20:20:40 +0000538When [lnum] is omitted, the first breakpoint in the function or file is
539deleted.
540The {name} must be exactly the same as what was typed for the ":breakadd"
541command. "explorer", "*explorer.vim" and "*explorer*" are different.
542
543
544LISTING BREAKPOINTS
545 *:breakl* *:breaklist*
546:breakl[ist]
547 List all breakpoints.
548
549
550OBSCURE
551
552 *:debugg* *:debuggreedy*
553:debugg[reedy]
554 Read debug mode commands from the normal input stream, instead
555 of getting them directly from the user. Only useful for test
556 scripts. Example: >
557 echo 'q^Mq' | vim -e -s -c debuggreedy -c 'breakadd file script.vim' -S script.vim
558
559:0debugg[reedy]
560 Undo ":debuggreedy": get debug mode commands directly from the
561 user, don't use typeahead for debug commands.
562
Bram Moolenaar05159a02005-02-26 23:04:13 +0000563==============================================================================
5646. Profiling *profile* *profiling*
565
566Profiling means that Vim measures the time that is spend on executing
567functions and/or scripts. The |+profile| feature is required for this.
568It is only included when Vim was compiled with "huge" features.
569{Vi does not have profiling}
570
Bram Moolenaar433f7c82006-03-21 21:29:36 +0000571You can also use the |reltime()| function to measure time. This only requires
572the |+reltime| feature, which is present more often.
573
Bram Moolenaar05159a02005-02-26 23:04:13 +0000574:prof[ile] start {fname} *:prof* *:profile* *E750*
575 Start profiling, write the output in {fname} upon exit.
Bram Moolenaar9b2200a2006-03-20 21:55:45 +0000576 If {fname} already exists it will be silently overwritten.
Bram Moolenaar05159a02005-02-26 23:04:13 +0000577 The variable |v:profiling| is set to one.
578
Bram Moolenaar9b2200a2006-03-20 21:55:45 +0000579:prof[ile] pause
580 Don't profile until the following ":profile continue". Can be
581 used when doing something that should not be counted (e.g., an
582 external command). Does not nest.
583
584:prof[ile] continue
585 Continue profiling after ":profile pause".
586
Bram Moolenaar05159a02005-02-26 23:04:13 +0000587:prof[ile] func {pattern}
588 Profile function that matches the pattern {pattern}.
589 See |:debug-name| for how {pattern} is used.
590
591:prof[ile][!] file {pattern}
592 Profile script file that matches the pattern {pattern}.
593 See |:debug-name| for how {pattern} is used.
594 This only profiles the script itself, not the functions
595 defined in it.
596 When the [!] is added then all functions defined in the script
Bram Moolenaar8cd06ca2005-02-28 22:44:58 +0000597 will also be profiled. But only if the script is loaded after
598 this command.
Bram Moolenaar05159a02005-02-26 23:04:13 +0000599
600
Bram Moolenaard9fba312005-06-26 22:34:35 +0000601:profd[el] ... *:profd* *:profdel*
602 Stop profiling for the arguments specified. See |:breakdel|
603 for the arguments.
604
605
Bram Moolenaar05159a02005-02-26 23:04:13 +0000606You must always start with a ":profile start fname" command. The resulting
607file is written when Vim exits. Here is an example of the output, with line
608numbers prepended for the explanation:
609
610 1 FUNCTION Test2() ~
611 2 Called 1 time ~
612 3 Total time: 0.155251 ~
613 4 Self time: 0.002006 ~
614 5 ~
615 6 count total (s) self (s) ~
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000616 7 9 0.000096 for i in range(8) ~
617 8 8 0.153655 0.000410 call Test3() ~
618 9 8 0.000070 endfor ~
619 10 " Ask a question ~
620 11 1 0.001341 echo input("give me an answer: ") ~
Bram Moolenaar05159a02005-02-26 23:04:13 +0000621
622The header (lines 1-4) gives the time for the whole function. The "Total"
623time is the time passed while the function was executing. The "Self" time is
624the "Total" time reduced by time spent in:
625- other user defined functions
626- sourced scripts
627- executed autocommands
628- external (shell) commands
629
630Lines 7-11 show the time spent in each executed line. Lines that are not
631executed do not count. Thus a comment line is never counted.
632
633The Count column shows how many times a line was executed. Note that the
634"for" command in line 7 is executed one more time as the following lines.
635That is because the line is also executed to detect the end of the loop.
636
637The time Vim spends waiting for user input isn't counted at all. Thus how
638long you take to respond to the input() prompt is irrelevant.
639
640Profiling should give a good indication of where time is spent, but keep in
641mind there are various things that may clobber the results:
642
643- The accuracy of the time measured depends on the gettimeofday() system
644 function. It may only be as accurate as 1/100 second, even though the times
645 are displayed in micro seconds.
646
647- Real elapsed time is measured, if other processes are busy they may cause
648 delays at unpredictable moments. You may want to run the profiling several
649 times and use the lowest results.
650
651- If you have several commands in one line you only get one time. Split the
652 line to see the time for the individual commands.
653
654- The time of the lines added up is mostly less than the time of the whole
655 function. There is some overhead in between.
656
657- Functions that are deleted before Vim exits will not produce profiling
658 information. You can check the |v:profiling| variable if needed: >
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000659 :if !v:profiling
Bram Moolenaar05159a02005-02-26 23:04:13 +0000660 : delfunc MyFunc
661 :endif
662<
Bram Moolenaar8cd06ca2005-02-28 22:44:58 +0000663- Profiling may give weird results on multi-processor systems, when sleep
664 mode kicks in or the processor frequency is reduced to save power.
Bram Moolenaar05159a02005-02-26 23:04:13 +0000665
Bram Moolenaarc81e5e72007-05-05 18:24:42 +0000666- The "self" time is wrong when a function is used recursively.
667
668
Bram Moolenaar071d4272004-06-13 20:20:40 +0000669 vim:tw=78:ts=8:ft=help:norl: