mirror of
https://github.com/neovim/neovim.git
synced 2024-12-29 14:41:06 -07:00
90fae3663f
Update runtime files. https://code.google.com/p/vim/source/detail?r=4abac79c0b7ae7aac0cb32d9930e155de628b63f
684 lines
26 KiB
Plaintext
684 lines
26 KiB
Plaintext
*repeat.txt* For Vim version 7.4. Last change: 2014 Oct 29
|
|
|
|
|
|
VIM REFERENCE MANUAL by Bram Moolenaar
|
|
|
|
|
|
Repeating commands, Vim scripts and debugging *repeating*
|
|
|
|
Chapter 26 of the user manual introduces repeating |usr_26.txt|.
|
|
|
|
1. Single repeats |single-repeat|
|
|
2. Multiple repeats |multi-repeat|
|
|
3. Complex repeats |complex-repeat|
|
|
4. Using Vim scripts |using-scripts|
|
|
5. Debugging scripts |debug-scripts|
|
|
6. Profiling |profiling|
|
|
|
|
==============================================================================
|
|
1. Single repeats *single-repeat*
|
|
|
|
*.*
|
|
. Repeat last change, with count replaced with [count].
|
|
Also repeat a yank command, when the 'y' flag is
|
|
included in 'cpoptions'. Does not repeat a
|
|
command-line command.
|
|
|
|
Simple changes can be repeated with the "." command. Without a count, the
|
|
count of the last change is used. If you enter a count, it will replace the
|
|
last one. |v:count| and |v:count1| will be set.
|
|
|
|
If the last change included a specification of a numbered register, the
|
|
register number will be incremented. See |redo-register| for an example how
|
|
to use this.
|
|
|
|
Note that when repeating a command that used a Visual selection, the same SIZE
|
|
of area is used, see |visual-repeat|.
|
|
|
|
*@:*
|
|
@: Repeat last command-line [count] times.
|
|
{not available when compiled without the
|
|
|+cmdline_hist| feature}
|
|
|
|
|
|
==============================================================================
|
|
2. Multiple repeats *multi-repeat*
|
|
|
|
*:g* *:global* *E147* *E148*
|
|
:[range]g[lobal]/{pattern}/[cmd]
|
|
Execute the Ex command [cmd] (default ":p") on the
|
|
lines within [range] where {pattern} matches.
|
|
|
|
:[range]g[lobal]!/{pattern}/[cmd]
|
|
Execute the Ex command [cmd] (default ":p") on the
|
|
lines within [range] where {pattern} does NOT match.
|
|
|
|
*:v* *:vglobal*
|
|
:[range]v[global]/{pattern}/[cmd]
|
|
Same as :g!.
|
|
|
|
Instead of the '/' which surrounds the {pattern}, you can use any other
|
|
single byte character, but not an alphabetic character, '\', '"' or '|'.
|
|
This is useful if you want to include a '/' in the search pattern or
|
|
replacement string.
|
|
|
|
For the definition of a pattern, see |pattern|.
|
|
|
|
NOTE [cmd] may contain a range; see |collapse| and |edit-paragraph-join| for
|
|
examples.
|
|
|
|
The global commands work by first scanning through the [range] lines and
|
|
marking each line where a match occurs (for a multi-line pattern, only the
|
|
start of the match matters).
|
|
In a second scan the [cmd] is executed for each marked line with its line
|
|
number prepended. For ":v" and ":g!" the command is executed for each not
|
|
marked line. If a line is deleted its mark disappears.
|
|
The default for [range] is the whole buffer (1,$). Use "CTRL-C" to interrupt
|
|
the command. If an error message is given for a line, the command for that
|
|
line is aborted and the global command continues with the next marked or
|
|
unmarked line.
|
|
|
|
To repeat a non-Ex command, you can use the ":normal" command: >
|
|
:g/pat/normal {commands}
|
|
Make sure that {commands} ends with a whole command, otherwise Vim will wait
|
|
for you to type the rest of the command for each match. The screen will not
|
|
have been updated, so you don't know what you are doing. See |:normal|.
|
|
|
|
The undo/redo command will undo/redo the whole global command at once.
|
|
The previous context mark will only be set once (with "''" you go back to
|
|
where the cursor was before the global command).
|
|
|
|
The global command sets both the last used search pattern and the last used
|
|
substitute pattern (this is vi compatible). This makes it easy to globally
|
|
replace a string:
|
|
:g/pat/s//PAT/g
|
|
This replaces all occurrences of "pat" with "PAT". The same can be done with:
|
|
:%s/pat/PAT/g
|
|
Which is two characters shorter!
|
|
|
|
When using "global" in Ex mode, a special case is using ":visual" as a
|
|
command. This will move to a matching line, go to Normal mode to let you
|
|
execute commands there until you use |Q| to return to Ex mode. This will be
|
|
repeated for each matching line. While doing this you cannot use ":global".
|
|
To abort this type CTRL-C twice.
|
|
|
|
==============================================================================
|
|
3. Complex repeats *complex-repeat*
|
|
|
|
*q* *recording*
|
|
q{0-9a-zA-Z"} Record typed characters into register {0-9a-zA-Z"}
|
|
(uppercase to append). The 'q' command is disabled
|
|
while executing a register, and it doesn't work inside
|
|
a mapping and |:normal|.
|
|
|
|
q Stops recording.
|
|
Implementation note: The 'q' that stops recording is
|
|
not stored in the register, unless it was the result
|
|
of a mapping
|
|
|
|
*@*
|
|
@{0-9a-z".=*+} Execute the contents of register {0-9a-z".=*+} [count]
|
|
times. Note that register '%' (name of the current
|
|
file) and '#' (name of the alternate file) cannot be
|
|
used.
|
|
The register is executed like a mapping, that means
|
|
that the difference between 'wildchar' and 'wildcharm'
|
|
applies.
|
|
For "@=" you are prompted to enter an expression. The
|
|
result of the expression is then executed.
|
|
See also |@:|.
|
|
|
|
*@@* *E748*
|
|
@@ Repeat the previous @{0-9a-z":*} [count] times.
|
|
|
|
*:@*
|
|
:[addr]@{0-9a-z".=*+} Execute the contents of register {0-9a-z".=*+} as an Ex
|
|
command. First set cursor at line [addr] (default is
|
|
current line). When the last line in the register does
|
|
not have a <CR> it will be added automatically when
|
|
the 'e' flag is present in 'cpoptions'.
|
|
For ":@=" the last used expression is used. The
|
|
result of evaluating the expression is executed as an
|
|
Ex command.
|
|
Mappings are not recognized in these commands.
|
|
|
|
*:@:*
|
|
:[addr]@: Repeat last command-line. First set cursor at line
|
|
[addr] (default is current line).
|
|
|
|
*:@@*
|
|
:[addr]@@ Repeat the previous :@{0-9a-z"}. First set cursor at
|
|
line [addr] (default is current line).
|
|
|
|
==============================================================================
|
|
4. Using Vim scripts *using-scripts*
|
|
|
|
For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|.
|
|
|
|
*:so* *:source* *load-vim-script*
|
|
:so[urce] {file} Read Ex commands from {file}. These are commands that
|
|
start with a ":".
|
|
Triggers the |SourcePre| autocommand.
|
|
|
|
:so[urce]! {file} Read Vim commands from {file}. These are commands
|
|
that are executed from Normal mode, like you type
|
|
them.
|
|
When used after |:global|, |:argdo|, |:windo|,
|
|
|:bufdo|, in a loop or when another command follows
|
|
the display won't be updated while executing the
|
|
commands.
|
|
|
|
*:ru* *:runtime*
|
|
:ru[ntime][!] {file} ..
|
|
Read Ex commands from {file} in each directory given
|
|
by 'runtimepath'. There is no error for non-existing
|
|
files. Example: >
|
|
:runtime syntax/c.vim
|
|
|
|
< There can be multiple {file} arguments, separated by
|
|
spaces. Each {file} is searched for in the first
|
|
directory from 'runtimepath', then in the second
|
|
directory, etc. Use a backslash to include a space
|
|
inside {file} (although it's better not to use spaces
|
|
in file names, it causes trouble).
|
|
|
|
When [!] is included, all found files are sourced.
|
|
When it is not included only the first found file is
|
|
sourced.
|
|
|
|
When {file} contains wildcards it is expanded to all
|
|
matching files. Example: >
|
|
:runtime! plugin/*.vim
|
|
< This is what Vim uses to load the plugin files when
|
|
starting up. This similar command: >
|
|
:runtime plugin/*.vim
|
|
< would source the first file only.
|
|
|
|
When 'verbose' is one or higher, there is a message
|
|
when no file could be found.
|
|
When 'verbose' is two or higher, there is a message
|
|
about each searched file.
|
|
|
|
:scripte[ncoding] [encoding] *:scripte* *:scriptencoding* *E167*
|
|
Specify the character encoding used in the script.
|
|
The following lines will be converted from [encoding]
|
|
to the value of the 'encoding' option, if they are
|
|
different. Examples: >
|
|
scriptencoding iso-8859-5
|
|
scriptencoding cp932
|
|
<
|
|
When [encoding] is empty, no conversion is done. This
|
|
can be used to restrict conversion to a sequence of
|
|
lines: >
|
|
scriptencoding euc-jp
|
|
... lines to be converted ...
|
|
scriptencoding
|
|
... not converted ...
|
|
|
|
< When conversion isn't supported by the system, there
|
|
is no error message and no conversion is done.
|
|
|
|
Don't use "ucs-2" or "ucs-4", scripts cannot be in
|
|
these encodings (they would contain NUL bytes).
|
|
When a sourced script starts with a BOM (Byte Order
|
|
Mark) in utf-8 format Vim will recognize it, no need
|
|
to use ":scriptencoding utf-8" then.
|
|
|
|
*:scrip* *:scriptnames*
|
|
:scrip[tnames] List all sourced script names, in the order they were
|
|
first sourced. The number is used for the script ID
|
|
|<SID>|.
|
|
|
|
*:fini* *:finish* *E168*
|
|
:fini[sh] Stop sourcing a script. Can only be used in a Vim
|
|
script file. This is a quick way to skip the rest of
|
|
the file. If it is used after a |:try| but before the
|
|
matching |:finally| (if present), the commands
|
|
following the ":finally" up to the matching |:endtry|
|
|
are executed first. This process applies to all
|
|
nested ":try"s in the script. The outermost ":endtry"
|
|
then stops sourcing the script.
|
|
|
|
All commands and command sequences can be repeated by putting them in a named
|
|
register and then executing it. There are two ways to get the commands in the
|
|
register:
|
|
- Use the record command "q". You type the commands once, and while they are
|
|
being executed they are stored in a register. Easy, because you can see
|
|
what you are doing. If you make a mistake, "p"ut the register into the
|
|
file, edit the command sequence, and then delete it into the register
|
|
again. You can continue recording by appending to the register (use an
|
|
uppercase letter).
|
|
- Delete or yank the command sequence into the register.
|
|
|
|
Often used command sequences can be put under a function key with the ':map'
|
|
command.
|
|
|
|
An alternative is to put the commands in a file, and execute them with the
|
|
':source!' command. Useful for long command sequences. Can be combined with
|
|
the ':map' command to put complicated commands under a function key.
|
|
|
|
The ':source' command reads Ex commands from a file line by line. You will
|
|
have to type any needed keyboard input. The ':source!' command reads from a
|
|
script file character by character, interpreting each character as if you
|
|
typed it.
|
|
|
|
Example: When you give the ":!ls" command you get the |hit-enter| prompt. If
|
|
you ':source' a file with the line "!ls" in it, you will have to type the
|
|
<Enter> yourself. But if you ':source!' a file with the line ":!ls" in it,
|
|
the next characters from that file are read until a <CR> is found. You will
|
|
not have to type <CR> yourself, unless ":!ls" was the last line in the file.
|
|
|
|
It is possible to put ':source[!]' commands in the script file, so you can
|
|
make a top-down hierarchy of script files. The ':source' command can be
|
|
nested as deep as the number of files that can be opened at one time (about
|
|
15). The ':source!' command can be nested up to 15 levels deep.
|
|
|
|
You can use the "<sfile>" string (literally, this is not a special key) inside
|
|
of the sourced file, in places where a file name is expected. It will be
|
|
replaced by the file name of the sourced file. For example, if you have a
|
|
"other.vimrc" file in the same directory as your ".vimrc" file, you can source
|
|
it from your ".vimrc" file with this command: >
|
|
:source <sfile>:h/other.vimrc
|
|
|
|
In script files terminal-dependent key codes are represented by
|
|
terminal-independent two character codes. This means that they can be used
|
|
in the same way on different kinds of terminals. The first character of a
|
|
key code is 0x80 or 128, shown on the screen as "~@". The second one can be
|
|
found in the list |key-notation|. Any of these codes can also be entered
|
|
with CTRL-V followed by the three digit decimal code. This does NOT work for
|
|
the <t_xx> termcap codes, these can only be used in mappings.
|
|
|
|
*:source_crnl* *W15*
|
|
MS-DOS and Win32: Files that are read with ":source" normally have
|
|
<CR><NL> <EOL>s. These always work. If you are using a file with <NL> <EOL>s
|
|
(for example, a file made on Unix), this will be recognized if 'fileformats'
|
|
is not empty and the first line does not end in a <CR>. This fails if the
|
|
first line has something like ":map <F1> :help^M", where "^M" is a <CR>. If
|
|
the first line ends in a <CR>, but following ones don't, you will get an error
|
|
message, because the <CR> from the first lines will be lost.
|
|
|
|
Mac Classic: Files that are read with ":source" normally have <CR> <EOL>s.
|
|
These always work. If you are using a file with <NL> <EOL>s (for example, a
|
|
file made on Unix), this will be recognized if 'fileformats' is not empty and
|
|
the first line does not end in a <CR>. Be careful not to use a file with <NL>
|
|
linebreaks which has a <CR> in first line.
|
|
|
|
On other systems, Vim expects ":source"ed files to end in a <NL>. These
|
|
always work. If you are using a file with <CR><NL> <EOL>s (for example, a
|
|
file made on MS-DOS), all lines will have a trailing <CR>. This may cause
|
|
problems for some commands (e.g., mappings). There is no automatic <EOL>
|
|
detection, because it's common to start with a line that defines a mapping
|
|
that ends in a <CR>, which will confuse the automaton.
|
|
|
|
*line-continuation*
|
|
Long lines in a ":source"d Ex command script file can be split by inserting
|
|
a line continuation symbol "\" (backslash) at the start of the next line.
|
|
There can be white space before the backslash, which is ignored.
|
|
|
|
Example: the lines >
|
|
:set comments=sr:/*,mb:*,el:*/,
|
|
\://,
|
|
\b:#,
|
|
\:%,
|
|
\n:>,
|
|
\fb:-
|
|
are interpreted as if they were given in one line:
|
|
:set comments=sr:/*,mb:*,el:*/,://,b:#,:%,n:>,fb:-
|
|
|
|
All leading whitespace characters in the line before a backslash are ignored.
|
|
Note however that trailing whitespace in the line before it cannot be
|
|
inserted freely; it depends on the position where a command is split up
|
|
whether additional whitespace is allowed or not.
|
|
|
|
When a space is required it's best to put it right after the backslash. A
|
|
space at the end of a line is hard to see and may be accidentally deleted. >
|
|
:syn match Comment
|
|
\ "very long regexp"
|
|
\ keepend
|
|
|
|
There is a problem with the ":append" and ":insert" commands: >
|
|
:1append
|
|
\asdf
|
|
.
|
|
The backslash is seen as a line-continuation symbol, thus this results in the
|
|
command: >
|
|
:1appendasdf
|
|
.
|
|
To avoid this, add the 'C' flag to the 'cpoptions' option: >
|
|
:set cpo+=C
|
|
:1append
|
|
\asdf
|
|
.
|
|
:set cpo-=C
|
|
|
|
Note that when the commands are inside a function, you need to add the 'C'
|
|
flag when defining the function, it is not relevant when executing it. >
|
|
:set cpo+=C
|
|
:function Foo()
|
|
:1append
|
|
\asdf
|
|
.
|
|
:endfunction
|
|
:set cpo-=C
|
|
|
|
Rationale:
|
|
Most programs work with a trailing backslash to indicate line
|
|
continuation. Using this in Vim would cause incompatibility with Vi.
|
|
For example for this Vi mapping: >
|
|
:map xx asdf\
|
|
< Therefore the unusual leading backslash is used.
|
|
|
|
==============================================================================
|
|
5. Debugging scripts *debug-scripts*
|
|
|
|
Besides the obvious messages that you can add to your scripts to find out what
|
|
they are doing, Vim offers a debug mode. This allows you to step through a
|
|
sourced file or user function and set breakpoints.
|
|
|
|
NOTE: The debugging mode is far from perfect. Debugging will have side
|
|
effects on how Vim works. You cannot use it to debug everything. For
|
|
example, the display is messed up by the debugging messages.
|
|
|
|
An alternative to debug mode is setting the 'verbose' option. With a bigger
|
|
number it will give more verbose messages about what Vim is doing.
|
|
|
|
|
|
STARTING DEBUG MODE *debug-mode*
|
|
|
|
To enter debugging mode use one of these methods:
|
|
1. Start Vim with the |-D| argument: >
|
|
vim -D file.txt
|
|
< Debugging will start as soon as the first vimrc file is sourced. This is
|
|
useful to find out what is happening when Vim is starting up. A side
|
|
effect is that Vim will switch the terminal mode before initialisations
|
|
have finished, with unpredictable results.
|
|
For a GUI-only version (Windows, Macintosh) the debugging will start as
|
|
soon as the GUI window has been opened. To make this happen early, add a
|
|
":gui" command in the vimrc file.
|
|
*:debug*
|
|
2. Run a command with ":debug" prepended. Debugging will only be done while
|
|
this command executes. Useful for debugging a specific script or user
|
|
function. And for scripts and functions used by autocommands. Example: >
|
|
:debug edit test.txt.gz
|
|
|
|
3. Set a breakpoint in a sourced file or user function. You could do this in
|
|
the command line: >
|
|
vim -c "breakadd file */explorer.vim" .
|
|
< This will run Vim and stop in the first line of the "explorer.vim" script.
|
|
Breakpoints can also be set while in debugging mode.
|
|
|
|
In debugging mode every executed command is displayed before it is executed.
|
|
Comment lines, empty lines and lines that are not executed are skipped. When
|
|
a line contains two commands, separated by "|", each command will be displayed
|
|
separately.
|
|
|
|
|
|
DEBUG MODE
|
|
|
|
Once in debugging mode, the usual Ex commands can be used. For example, to
|
|
inspect the value of a variable: >
|
|
echo idx
|
|
When inside a user function, this will print the value of the local variable
|
|
"idx". Prepend "g:" to get the value of a global variable: >
|
|
echo g:idx
|
|
All commands are executed in the context of the current function or script.
|
|
You can also set options, for example setting or resetting 'verbose' will show
|
|
what happens, but you might want to set it just before executing the lines you
|
|
are interested in: >
|
|
:set verbose=20
|
|
|
|
Commands that require updating the screen should be avoided, because their
|
|
effect won't be noticed until after leaving debug mode. For example: >
|
|
:help
|
|
won't be very helpful.
|
|
|
|
There is a separate command-line history for debug mode.
|
|
|
|
The line number for a function line is relative to the start of the function.
|
|
If you have trouble figuring out where you are, edit the file that defines
|
|
the function in another Vim, search for the start of the function and do
|
|
"99j". Replace "99" with the line number.
|
|
|
|
Additionally, these commands can be used:
|
|
*>cont*
|
|
cont Continue execution until the next breakpoint is hit.
|
|
*>quit*
|
|
quit Abort execution. This is like using CTRL-C, some
|
|
things might still be executed, doesn't abort
|
|
everything. Still stops at the next breakpoint.
|
|
*>next*
|
|
next Execute the command and come back to debug mode when
|
|
it's finished. This steps over user function calls
|
|
and sourced files.
|
|
*>step*
|
|
step Execute the command and come back to debug mode for
|
|
the next command. This steps into called user
|
|
functions and sourced files.
|
|
*>interrupt*
|
|
interrupt This is like using CTRL-C, but unlike ">quit" comes
|
|
back to debug mode for the next command that is
|
|
executed. Useful for testing |:finally| and |:catch|
|
|
on interrupt exceptions.
|
|
*>finish*
|
|
finish Finish the current script or user function and come
|
|
back to debug mode for the command after the one that
|
|
sourced or called it.
|
|
|
|
About the additional commands in debug mode:
|
|
- There is no command-line completion for them, you get the completion for the
|
|
normal Ex commands only.
|
|
- You can shorten them, up to a single character: "c", "n", "s" and "f".
|
|
- Hitting <CR> will repeat the previous one. When doing another command, this
|
|
is reset (because it's not clear what you want to repeat).
|
|
- When you want to use the Ex command with the same name, prepend a colon:
|
|
":cont", ":next", ":finish" (or shorter).
|
|
|
|
|
|
DEFINING BREAKPOINTS
|
|
*:breaka* *:breakadd*
|
|
:breaka[dd] func [lnum] {name}
|
|
Set a breakpoint in a function. Example: >
|
|
:breakadd func Explore
|
|
< Doesn't check for a valid function name, thus the breakpoint
|
|
can be set before the function is defined.
|
|
|
|
:breaka[dd] file [lnum] {name}
|
|
Set a breakpoint in a sourced file. Example: >
|
|
:breakadd file 43 .vimrc
|
|
|
|
:breaka[dd] here
|
|
Set a breakpoint in the current line of the current file.
|
|
Like doing: >
|
|
:breakadd file <cursor-line> <current-file>
|
|
< Note that this only works for commands that are executed when
|
|
sourcing the file, not for a function defined in that file.
|
|
|
|
The [lnum] is the line number of the breakpoint. Vim will stop at or after
|
|
this line. When omitted line 1 is used.
|
|
|
|
*:debug-name*
|
|
{name} is a pattern that is matched with the file or function name. The
|
|
pattern is like what is used for autocommands. There must be a full match (as
|
|
if the pattern starts with "^" and ends in "$"). A "*" matches any sequence
|
|
of characters. 'ignorecase' is not used, but "\c" can be used in the pattern
|
|
to ignore case |/\c|. Don't include the () for the function name!
|
|
|
|
The match for sourced scripts is done against the full file name. If no path
|
|
is specified the current directory is used. Examples: >
|
|
breakadd file explorer.vim
|
|
matches "explorer.vim" in the current directory. >
|
|
breakadd file *explorer.vim
|
|
matches ".../plugin/explorer.vim", ".../plugin/iexplorer.vim", etc. >
|
|
breakadd file */explorer.vim
|
|
matches ".../plugin/explorer.vim" and "explorer.vim" in any other directory.
|
|
|
|
The match for functions is done against the name as it's shown in the output
|
|
of ":function". For local functions this means that something like "<SNR>99_"
|
|
is prepended.
|
|
|
|
Note that functions are first loaded and later executed. When they are loaded
|
|
the "file" breakpoints are checked, when they are executed the "func"
|
|
breakpoints.
|
|
|
|
|
|
DELETING BREAKPOINTS
|
|
*:breakd* *:breakdel* *E161*
|
|
:breakd[el] {nr}
|
|
Delete breakpoint {nr}. Use |:breaklist| to see the number of
|
|
each breakpoint.
|
|
|
|
:breakd[el] *
|
|
Delete all breakpoints.
|
|
|
|
:breakd[el] func [lnum] {name}
|
|
Delete a breakpoint in a function.
|
|
|
|
:breakd[el] file [lnum] {name}
|
|
Delete a breakpoint in a sourced file.
|
|
|
|
:breakd[el] here
|
|
Delete a breakpoint at the current line of the current file.
|
|
|
|
When [lnum] is omitted, the first breakpoint in the function or file is
|
|
deleted.
|
|
The {name} must be exactly the same as what was typed for the ":breakadd"
|
|
command. "explorer", "*explorer.vim" and "*explorer*" are different.
|
|
|
|
|
|
LISTING BREAKPOINTS
|
|
*:breakl* *:breaklist*
|
|
:breakl[ist]
|
|
List all breakpoints.
|
|
|
|
|
|
OBSCURE
|
|
|
|
*:debugg* *:debuggreedy*
|
|
:debugg[reedy]
|
|
Read debug mode commands from the normal input stream, instead
|
|
of getting them directly from the user. Only useful for test
|
|
scripts. Example: >
|
|
echo 'q^Mq' | vim -e -s -c debuggreedy -c 'breakadd file script.vim' -S script.vim
|
|
|
|
:0debugg[reedy]
|
|
Undo ":debuggreedy": get debug mode commands directly from the
|
|
user, don't use typeahead for debug commands.
|
|
|
|
==============================================================================
|
|
6. Profiling *profile* *profiling*
|
|
|
|
Profiling means that Vim measures the time that is spent on executing
|
|
functions and/or scripts. The |+profile| feature is required for this.
|
|
It is only included when Vim was compiled with "huge" features.
|
|
|
|
You can also use the |reltime()| function to measure time. This only requires
|
|
the |+reltime| feature, which is present more often.
|
|
|
|
For profiling syntax highlighting see |:syntime|.
|
|
|
|
For example, to profile the one_script.vim script file: >
|
|
:profile start /tmp/one_script_profile
|
|
:profile file one_script.vim
|
|
:source one_script.vim
|
|
:exit
|
|
|
|
|
|
:prof[ile] start {fname} *:prof* *:profile* *E750*
|
|
Start profiling, write the output in {fname} upon exit.
|
|
If {fname} already exists it will be silently overwritten.
|
|
The variable |v:profiling| is set to one.
|
|
|
|
:prof[ile] pause
|
|
Don't profile until the following ":profile continue". Can be
|
|
used when doing something that should not be counted (e.g., an
|
|
external command). Does not nest.
|
|
|
|
:prof[ile] continue
|
|
Continue profiling after ":profile pause".
|
|
|
|
:prof[ile] func {pattern}
|
|
Profile function that matches the pattern {pattern}.
|
|
See |:debug-name| for how {pattern} is used.
|
|
|
|
:prof[ile][!] file {pattern}
|
|
Profile script file that matches the pattern {pattern}.
|
|
See |:debug-name| for how {pattern} is used.
|
|
This only profiles the script itself, not the functions
|
|
defined in it.
|
|
When the [!] is added then all functions defined in the script
|
|
will also be profiled.
|
|
Note that profiling only starts when the script is loaded
|
|
after this command. A :profile command in the script itself
|
|
won't work.
|
|
|
|
|
|
:profd[el] ... *:profd* *:profdel*
|
|
Stop profiling for the arguments specified. See |:breakdel|
|
|
for the arguments.
|
|
|
|
|
|
You must always start with a ":profile start fname" command. The resulting
|
|
file is written when Vim exits. Here is an example of the output, with line
|
|
numbers prepended for the explanation:
|
|
|
|
1 FUNCTION Test2() ~
|
|
2 Called 1 time ~
|
|
3 Total time: 0.155251 ~
|
|
4 Self time: 0.002006 ~
|
|
5 ~
|
|
6 count total (s) self (s) ~
|
|
7 9 0.000096 for i in range(8) ~
|
|
8 8 0.153655 0.000410 call Test3() ~
|
|
9 8 0.000070 endfor ~
|
|
10 " Ask a question ~
|
|
11 1 0.001341 echo input("give me an answer: ") ~
|
|
|
|
The header (lines 1-4) gives the time for the whole function. The "Total"
|
|
time is the time passed while the function was executing. The "Self" time is
|
|
the "Total" time reduced by time spent in:
|
|
- other user defined functions
|
|
- sourced scripts
|
|
- executed autocommands
|
|
- external (shell) commands
|
|
|
|
Lines 7-11 show the time spent in each executed line. Lines that are not
|
|
executed do not count. Thus a comment line is never counted.
|
|
|
|
The Count column shows how many times a line was executed. Note that the
|
|
"for" command in line 7 is executed one more time as the following lines.
|
|
That is because the line is also executed to detect the end of the loop.
|
|
|
|
The time Vim spends waiting for user input isn't counted at all. Thus how
|
|
long you take to respond to the input() prompt is irrelevant.
|
|
|
|
Profiling should give a good indication of where time is spent, but keep in
|
|
mind there are various things that may clobber the results:
|
|
|
|
- The accuracy of the time measured depends on the gettimeofday() system
|
|
function. It may only be as accurate as 1/100 second, even though the times
|
|
are displayed in micro seconds.
|
|
|
|
- Real elapsed time is measured, if other processes are busy they may cause
|
|
delays at unpredictable moments. You may want to run the profiling several
|
|
times and use the lowest results.
|
|
|
|
- If you have several commands in one line you only get one time. Split the
|
|
line to see the time for the individual commands.
|
|
|
|
- The time of the lines added up is mostly less than the time of the whole
|
|
function. There is some overhead in between.
|
|
|
|
- Functions that are deleted before Vim exits will not produce profiling
|
|
information. You can check the |v:profiling| variable if needed: >
|
|
:if !v:profiling
|
|
: delfunc MyFunc
|
|
:endif
|
|
<
|
|
- Profiling may give weird results on multi-processor systems, when sleep
|
|
mode kicks in or the processor frequency is reduced to save power.
|
|
|
|
- The "self" time is wrong when a function is used recursively.
|
|
|
|
|
|
vim:tw=78:ts=8:ft=help:norl:
|