mirror of
https://github.com/vim/vim
synced 2025-03-14 22:07:51 +01:00
closes: #15745 Co-authored-by: Danilo Rezende <returndanilo@users.noreply.github.com> Signed-off-by: Christian Brabandt <cb@256bit.org>
1504 lines
57 KiB
Text
1504 lines
57 KiB
Text
*repeat.txt* For Vim version 9.1. Last change: 2024 Oct 16
|
||
|
||
|
||
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. Using Vim packages |packages|
|
||
6. Creating Vim packages |package-create|
|
||
7. Debugging scripts |debug-scripts|
|
||
8. 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* *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!.
|
||
|
||
Example: >
|
||
:g/^Obsolete/d _
|
||
Using the underscore after `:d` avoids clobbering registers or the clipboard.
|
||
This also makes it faster.
|
||
|
||
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, as if the cursor
|
||
was in that line. 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.
|
||
*E147*
|
||
When the command is used recursively, it only works on one line. Giving a
|
||
range is then not allowed. This is useful to find all lines that match a
|
||
pattern and do not match another pattern: >
|
||
:g/found/v/notfound/{cmd}
|
||
This first finds all lines containing "found", but only executes {cmd} when
|
||
there is no match for "notfound".
|
||
|
||
Any Ex command can be used, see |ex-cmd-index|. To execute a Normal mode
|
||
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|.
|
||
|
||
Note: If the register being used for recording is also
|
||
used for |y| and |p| the result is most likely not
|
||
what is expected, because the put will paste the
|
||
recorded macro and the yank will overwrite the
|
||
recorded macro.
|
||
|
||
Note: The recording happens while you type, replaying
|
||
the register happens as if the keys come from a
|
||
mapping. This matters, for example, for undo, which
|
||
only syncs when commands were typed.
|
||
|
||
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, and undo might not be synced in the same way.
|
||
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.
|
||
When the |line-continuation| character (\) is present
|
||
at the beginning of a line in a linewise register,
|
||
then it is combined with the previous line. This is
|
||
useful for yanking and executing parts of a Vim
|
||
script.
|
||
Future: Will execute the register for each line in the
|
||
address range.
|
||
|
||
:[addr]*{0-9a-z".=+} *:star-compatible*
|
||
When '*' is present in 'cpoptions' |cpo-star|, use
|
||
":*" in the same way as ":@". This is NOT the default
|
||
when 'nocompatible' is used. When the '*' flag is not
|
||
present in 'cpoptions', ":*" is an alias for ":'<,'>",
|
||
select the Visual area |:star|.
|
||
|
||
*:@:*
|
||
:[addr]@: Repeat last command-line. First set cursor at line
|
||
[addr] (default is current line).
|
||
|
||
:[addr]@ *:@@*
|
||
:[addr]@@ Repeat the previous :@{register}. 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.
|
||
*:source-range*
|
||
:[range]so[urce] [++clear]
|
||
Read Ex commands from the [range] of lines in the
|
||
current buffer. When [range] is omitted read all
|
||
lines.
|
||
|
||
When sourcing commands from the current buffer, the
|
||
same script-ID |<SID>| is used even if the buffer is
|
||
sourced multiple times. If a buffer is sourced more
|
||
than once, then the functions in the buffer are
|
||
defined again.
|
||
|
||
To source a range of lines that doesn't start with the
|
||
|:vim9script| command in Vim9 script context, the
|
||
|:vim9cmd| modifier can be used. If you use a Visual
|
||
selection and type ":", the range in the form "'<,'>"
|
||
can come before it: >
|
||
:'<,'>vim9cmd source
|
||
< Otherwise the range goes after the modifier and must
|
||
have a colon prefixed, like all Vim9 ranges: >
|
||
:vim9cmd :5,9source
|
||
|
||
< When a range of lines in a buffer is sourced in the
|
||
Vim9 script context, the previously defined
|
||
script-local variables and functions are not cleared.
|
||
This works like the range started with the
|
||
":vim9script noclear" command. The "++clear" argument
|
||
can be used to clear the script-local variables and
|
||
functions before sourcing the script. This works like
|
||
the range started with the `:vim9script` command
|
||
without the "noclear" argument. See |vim9-reload| for
|
||
more information.
|
||
Examples: >
|
||
:4,5source
|
||
:10,18source ++clear
|
||
<
|
||
*:source!*
|
||
: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.
|
||
Cannot be used in the |sandbox|.
|
||
|
||
*:ru* *:runtime*
|
||
:ru[ntime][!] [where] {file} ..
|
||
Read Ex commands from {file} in each directory given
|
||
by 'runtimepath' and/or 'packpath'. 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 [where] is omitted only 'runtimepath' is used.
|
||
Other values:
|
||
START search under "start" in 'packpath'
|
||
OPT search under "opt" in 'packpath'
|
||
PACK search under "start" and "opt" in
|
||
'packpath'
|
||
ALL first use 'runtimepath', then search
|
||
under "start" and "opt" in 'packpath'
|
||
|
||
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.
|
||
|
||
*:pa* *:packadd* *E919*
|
||
:pa[ckadd][!] {name} Search for an optional plugin directory in 'packpath'
|
||
and source any plugin files found. The directory must
|
||
match:
|
||
pack/*/opt/{name} ~
|
||
The directory is added to 'runtimepath' if it wasn't
|
||
there yet.
|
||
If the directory pack/*/opt/{name}/after exists it is
|
||
added at the end of 'runtimepath'.
|
||
|
||
If loading packages from "pack/*/start" was skipped,
|
||
then this directory is searched first:
|
||
pack/*/start/{name} ~
|
||
|
||
Note that {name} is the directory name, not the name
|
||
of the .vim file. All the files matching the pattern
|
||
pack/*/opt/{name}/plugin/**/*.vim ~
|
||
will be sourced. This allows for using subdirectories
|
||
below "plugin", just like with plugins in
|
||
'runtimepath'.
|
||
|
||
If the filetype detection was not enabled yet (this
|
||
is usually done with a `syntax enable` or `filetype on`
|
||
command in your .vimrc file), this will also look
|
||
for "{name}/ftdetect/*.vim" files.
|
||
|
||
When the optional ! is added no plugin files or
|
||
ftdetect scripts are loaded, only the matching
|
||
directories are added to 'runtimepath'. This is
|
||
useful in your .vimrc. The plugins will then be
|
||
loaded during initialization, see |load-plugins| (note
|
||
that the loading order will be reversed, because each
|
||
directory is inserted before others).
|
||
Note that for ftdetect scripts to be loaded
|
||
you will need to write `filetype plugin indent on`
|
||
AFTER all `packadd!` commands.
|
||
|
||
Also see |pack-add|.
|
||
{only available when compiled with |+eval|}
|
||
|
||
*:packl* *:packloadall*
|
||
:packl[oadall][!] Load all packages in the "start" directory under each
|
||
entry in 'packpath'.
|
||
|
||
First all the directories found are added to
|
||
'runtimepath', then the plugins found in the
|
||
directories are sourced. This allows for a plugin to
|
||
depend on something of another plugin, e.g. an
|
||
"autoload" directory. See |packload-two-steps| for
|
||
how this can be useful.
|
||
|
||
This is normally done automatically during startup,
|
||
after loading your .vimrc file. With this command it
|
||
can be done earlier.
|
||
|
||
Packages will be loaded only once. Using
|
||
`:packloadall` a second time will have no effect.
|
||
When the optional ! is added this command will load
|
||
packages even when done before.
|
||
|
||
Note that when using `:packloadall` in the |vimrc|
|
||
file, the 'runtimepath' option is updated, and later
|
||
all plugins in 'runtimepath' will be loaded, which
|
||
means they are loaded again. Plugins are expected to
|
||
handle that.
|
||
|
||
An error only causes sourcing the script where it
|
||
happens to be aborted, further plugins will be loaded.
|
||
See |packages|.
|
||
{only available when compiled with |+eval|}
|
||
|
||
: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. When a
|
||
line can't be converted there is no error and the
|
||
original line is kept.
|
||
|
||
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.
|
||
|
||
If you set the 'encoding' option in your |.vimrc|,
|
||
`:scriptencoding` must be placed after that. E.g.: >
|
||
set encoding=utf-8
|
||
scriptencoding utf-8
|
||
<
|
||
|
||
:scriptv[ersion] {version} *:scriptv* *:scriptversion*
|
||
*E999* *E984* *E1040*
|
||
Specify the version of Vim for the lines that follow
|
||
in the same file. Only applies at the toplevel of
|
||
sourced scripts, not inside functions.
|
||
|
||
If {version} is higher than what the current Vim
|
||
version supports E999 will be given. You either need
|
||
to rewrite the script to make it work with an older
|
||
Vim version, or update Vim to a newer version. See
|
||
|vimscript-version| for what changed between versions.
|
||
|
||
:vim9s[cript] [noclear] *:vim9s* *:vim9script*
|
||
Marks a script file as containing |Vim9-script|
|
||
commands. Also see |vim9-namespace|. *E1038*
|
||
Must be the first command in the file. *E1039*
|
||
For [noclear] see |vim9-reload|.
|
||
Without the |+eval| feature this changes the syntax
|
||
for some commands.
|
||
See |:vim9cmd| for executing one command with Vim9
|
||
syntax and semantics.
|
||
|
||
*:scr* *:scriptnames*
|
||
:scr[iptnames] List all sourced script names, in the order they were
|
||
first encountered. The number is used for the script
|
||
ID |<SID>|.
|
||
For a script that was used with `import autoload` but
|
||
was not actually sourced yet an "A" is shown after the
|
||
script ID.
|
||
For a script that was referred to by one name but
|
||
after resolving symbolic links got sourced with
|
||
another name the other script is after "->". E.g.
|
||
"20->22" means script 20 was sourced as script 22.
|
||
Also see `getscriptinfo()`.
|
||
{not available when compiled without the |+eval|
|
||
feature}
|
||
|
||
:scr[iptnames][!] {scriptId} *:script*
|
||
Edit script {scriptId}. Although ":scriptnames name"
|
||
works, using ":script name" is recommended.
|
||
When the current buffer can't be |abandon|ed and the !
|
||
is not present, the command fails.
|
||
|
||
*: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 or a buffer 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*
|
||
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-Windows), 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
|
||
|
||
In |Vim9| script the backslash can often be omitted, but not always.
|
||
See |vim9-line-continuation|.
|
||
|
||
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
|
||
<
|
||
*line-continuation-comment*
|
||
To add a comment in between the lines start with '"\ '. Notice the space
|
||
after the backslash. Example: >
|
||
let array = [
|
||
"\ first entry comment
|
||
\ 'first',
|
||
"\ second entry comment
|
||
\ 'second',
|
||
\ ]
|
||
|
||
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.
|
||
|
||
Starting a comment in a continuation line results in all following
|
||
continuation lines to be part of the comment. Since it was like this
|
||
for a long time, when making it possible to add a comment halfway a
|
||
sequence of continuation lines, it was not possible to use \", since
|
||
that was a valid continuation line. Using '"\ ' comes closest, even
|
||
though it may look a bit weird. Requiring the space after the
|
||
backslash is to make it very unlikely this is a normal comment line.
|
||
|
||
==============================================================================
|
||
5. Using Vim packages *packages*
|
||
|
||
A Vim package is a directory that contains one or more plugins. The
|
||
advantages over normal plugins:
|
||
- A package can be downloaded as an archive and unpacked in its own directory.
|
||
Thus the files are not mixed with files of other plugins. That makes it
|
||
easy to update and remove.
|
||
- A package can be a git, mercurial, etc. repository. That makes it really
|
||
easy to update.
|
||
- A package can contain multiple plugins that depend on each other.
|
||
- A package can contain plugins that are automatically loaded on startup and
|
||
ones that are only loaded when needed with `:packadd`.
|
||
|
||
|
||
Using a package and loading automatically ~
|
||
|
||
Let's assume your Vim files are in the "~/.vim" directory and you want to add a
|
||
package from a zip archive "/tmp/foopack.zip": >
|
||
% mkdir -p ~/.vim/pack/foo
|
||
% cd ~/.vim/pack/foo
|
||
% unzip /tmp/foopack.zip
|
||
|
||
The directory name "foo" is arbitrary, you can pick anything you like.
|
||
|
||
You would now have these files under ~/.vim:
|
||
pack/foo/README.txt
|
||
pack/foo/start/foobar/plugin/foo.vim
|
||
pack/foo/start/foobar/syntax/some.vim
|
||
pack/foo/opt/foodebug/plugin/debugger.vim
|
||
|
||
When Vim starts up, after processing your .vimrc, it scans all directories in
|
||
'packpath' for plugins under the "pack/*/start" directory. First all those
|
||
directories are added to 'runtimepath'. Then all the plugins are loaded.
|
||
See |packload-two-steps| for how these two steps can be useful.
|
||
|
||
To allow for calling into package functionality while parsing your .vimrc,
|
||
|:colorscheme| and |autoload| will both automatically search under 'packpath'
|
||
as well in addition to 'runtimepath'. See the documentation for each for
|
||
details.
|
||
|
||
In the example Vim will find "pack/foo/start/foobar/plugin/foo.vim" and adds
|
||
"~/.vim/pack/foo/start/foobar" to 'runtimepath'.
|
||
|
||
If the "foobar" plugin kicks in and sets the 'filetype' to "some", Vim will
|
||
find the syntax/some.vim file, because its directory is in 'runtimepath'.
|
||
|
||
Vim will also load ftdetect files, if there are any.
|
||
|
||
Note that the files under "pack/foo/opt" are not loaded automatically, only the
|
||
ones under "pack/foo/start". See |pack-add| below for how the "opt" directory
|
||
is used.
|
||
|
||
Loading packages automatically will not happen if loading plugins is disabled,
|
||
see |load-plugins|.
|
||
|
||
To load packages earlier, so that 'runtimepath' gets updated: >
|
||
:packloadall
|
||
This also works when loading plugins is disabled. The automatic loading will
|
||
only happen once.
|
||
|
||
If the package has an "after" directory, that directory is added to the end of
|
||
'runtimepath', so that anything there will be loaded later.
|
||
|
||
|
||
Using a single plugin and loading it automatically ~
|
||
|
||
If you don't have a package but a single plugin, you need to create the extra
|
||
directory level: >
|
||
% mkdir -p ~/.vim/pack/foo/start/foobar
|
||
% cd ~/.vim/pack/foo/start/foobar
|
||
% unzip /tmp/someplugin.zip
|
||
|
||
You would now have these files:
|
||
pack/foo/start/foobar/plugin/foo.vim
|
||
pack/foo/start/foobar/syntax/some.vim
|
||
|
||
From here it works like above.
|
||
|
||
|
||
Optional plugins ~
|
||
*pack-add*
|
||
To load an optional plugin from a pack use the `:packadd` command: >
|
||
:packadd foodebug
|
||
This searches for "pack/*/opt/foodebug" in 'packpath' and will find
|
||
~/.vim/pack/foo/opt/foodebug/plugin/debugger.vim and source it.
|
||
|
||
This could be done if some conditions are met. For example, depending on
|
||
whether Vim supports a feature or a dependency is missing.
|
||
|
||
You can also load an optional plugin at startup, by putting this command in
|
||
your |.vimrc|: >
|
||
:packadd! foodebug
|
||
The extra "!" is so that the plugin isn't loaded if Vim was started with
|
||
|--noplugin|.
|
||
|
||
It is perfectly normal for a package to only have files in the "opt"
|
||
directory. You then need to load each plugin when you want to use it.
|
||
|
||
|
||
Where to put what ~
|
||
|
||
Since color schemes, loaded with `:colorscheme`, are found below
|
||
"pack/*/start" and "pack/*/opt", you could put them anywhere. We recommend
|
||
you put them below "pack/*/opt", for example
|
||
".vim/pack/mycolors/opt/dark/colors/very_dark.vim".
|
||
|
||
Filetype plugins should go under "pack/*/start", so that they are always
|
||
found. Unless you have more than one plugin for a file type and want to
|
||
select which one to load with `:packadd`. E.g. depending on the compiler
|
||
version: >
|
||
if foo_compiler_version > 34
|
||
packadd foo_new
|
||
else
|
||
packadd foo_old
|
||
endif
|
||
|
||
The "after" directory is most likely not useful in a package. It's not
|
||
disallowed though.
|
||
|
||
==============================================================================
|
||
6. Creating Vim packages *package-create*
|
||
|
||
This assumes you write one or more plugins that you distribute as a package.
|
||
|
||
If you have two unrelated plugins you would use two packages, so that Vim
|
||
users can choose what they include or not. Or you can decide to use one
|
||
package with optional plugins, and tell the user to add the preferred ones with
|
||
`:packadd`.
|
||
|
||
Decide how you want to distribute the package. You can create an archive or
|
||
you could use a repository. An archive can be used by more users, but is a
|
||
bit harder to update to a new version. A repository can usually be kept
|
||
up-to-date easily, but it requires a program like "git" to be available.
|
||
You can do both, github can automatically create an archive for a release.
|
||
|
||
Your directory layout would be like this:
|
||
start/foobar/plugin/foo.vim " always loaded, defines commands
|
||
start/foobar/plugin/bar.vim " always loaded, defines commands
|
||
start/foobar/autoload/foo.vim " loaded when foo command used
|
||
start/foobar/doc/foo.txt " help for foo.vim
|
||
start/foobar/doc/tags " help tags
|
||
start/foobar/lang/<lang_id>/LC_MESSAGES/foobar.mo
|
||
" messages for the plugin in the
|
||
" <lang_id> language. These files are
|
||
" optional.
|
||
opt/fooextra/plugin/extra.vim " optional plugin, defines commands
|
||
opt/fooextra/autoload/extra.vim " loaded when extra command used
|
||
opt/fooextra/doc/extra.txt " help for extra.vim
|
||
opt/fooextra/doc/tags " help tags
|
||
|
||
This allows for the user to do: >
|
||
mkdir ~/.vim/pack
|
||
cd ~/.vim/pack
|
||
git clone https://github.com/you/foobar.git myfoobar
|
||
<
|
||
Here "myfoobar" is a name that the user can choose, the only condition is that
|
||
it differs from other packages.
|
||
|
||
In your documentation you explain what the plugins do, and tell the user how
|
||
to load the optional plugin: >
|
||
:packadd! fooextra
|
||
<
|
||
You could add this packadd command in one of your plugins, to be executed when
|
||
the optional plugin is needed.
|
||
|
||
*package-doc* *package-documentation*
|
||
Run the `:helptags` command to generate the doc/tags file. Including this
|
||
generated file in the package means that the user can drop the package in the
|
||
pack directory and the help command works right away. Don't forget to re-run
|
||
the command after changing the plugin help: >
|
||
:helptags path/start/foobar/doc
|
||
:helptags path/opt/fooextra/doc
|
||
<
|
||
*package-translation*
|
||
In order for a plugin to display translated messages, a few steps are
|
||
required.
|
||
The author of the plugin who likes to translate messages must define the name
|
||
of the package and the location of the directory where the translations can be
|
||
found using the |bindtextdomain()| function: >
|
||
:call bindtextdomain("foobar",
|
||
\ fnamemodify(expand("<script>"), ':p:h') .. '/../lang/')
|
||
<
|
||
Where:
|
||
"foobar" is the unique package identifier by which the |gettext()|
|
||
function will later search for translation strings for this
|
||
plugin.
|
||
"lang/" is the relative or absolute path to the directory structure
|
||
where the translation file is located.
|
||
|
||
The directory structure where the message translation files should be placed
|
||
is (from the top-level directory of the package):
|
||
"lang/<lang_id>/LC_MESSAGES". For the format of <lang_id> see |multi-lang|.
|
||
This function needs to be called only once during the initialization of the
|
||
plugin.
|
||
Once this is done, the |gettext()| function can be used to retrieve translated
|
||
messages: >
|
||
:echo gettext("Hello", "foobar")
|
||
<
|
||
Where:
|
||
"Hello" the message "Hello" to be translated into the user's language
|
||
|:lang|
|
||
"foobar" the package identifier, which was previously defined using the
|
||
|bindtextdomain()| function.
|
||
|
||
After that you need to create a template file for translation - POT-file.
|
||
To do this, execute the following commands (using the Vim repository): >
|
||
cd ~/forkvim/src/po
|
||
make -f Makefile "PLUGPACKAGE={package}" \
|
||
"PO_PLUG_INPUTLIST={path/to/scripts-that-need-translations.vim}" \
|
||
["POT_PLUGPACKAGE_PATH={path/where/to/write/{package}.pot}" \]
|
||
["VIMPROG={path/to/vim} \]
|
||
{package}.pot
|
||
<
|
||
Where:
|
||
PLUGPACKAGE A variable containing the name of the package that we
|
||
specified in the |bindtextdomain()| and
|
||
|gettext()| functions, for example, "foobar".
|
||
PO_PLUG_INPUTLIST A variable containing scripts that have strings
|
||
to translate, i.e. where we specified the |gettext()|
|
||
function. Scripts are specified with an absolute
|
||
or relative path. Example: start/foobar/plugin/bar.vim
|
||
use blanks to separate scripts.
|
||
POT_PLUGPACKAGE_PATH A variable containing the directory where the prepared
|
||
POT file will be saved. This is not a required variable,
|
||
if no directory is specified, then the POT file will
|
||
be placed in the "src/po" directory.
|
||
VIMPROG A variable containing a directory with a working Vim.
|
||
If the Vim editor is already built and installed, and
|
||
is contained in the $PATH environment variable,
|
||
then you can specify just the name of the vim
|
||
executable.
|
||
{package}.pot This is the Target. It is specified as the name of
|
||
the package, for example, "foobar" with the addition
|
||
of the .pot extension.
|
||
Once a POT file is created, its contents are copied into separate PO files for
|
||
each language for which the translation will be prepared.
|
||
|
||
When the translation is finished, it is necessary to convert the PO files into
|
||
binary MO-files format and place these MO-files into the "lang/" directory, the
|
||
structure of which we created earlier.
|
||
To do this, run the following commands:
|
||
>
|
||
cd ~/forkvim/src/po
|
||
make -f Makefile "PLUGPACKAGE={package}" \
|
||
"PO_PLUGPACKAGE={path/to/{lang}.po}" \
|
||
["MO_PLUGPACKAGE_PATH={path/to/lang/<lang_id>/LC_MESSAGES}" \]
|
||
{package}.mo
|
||
<
|
||
Where:
|
||
PLUGPACKAGE A variable containing the name of the package that we
|
||
specified in the |bindtextdomain()| and |gettext()|
|
||
functions, for example, "foobar".
|
||
PO_PLUGPACKAGE A variable containing a PO file. The file is specified
|
||
with an absolute or relative path. For example,
|
||
"~/myproject/translate/en.po"
|
||
MO_PLUGPACKAGE_PATH A variable containing the structure of the "lang/"
|
||
directory, where the file with translations will be
|
||
placed, for example, "foobar.mo". This is not
|
||
a required variable, if the directory is not specified,
|
||
the MO file will be saved in the "src/po" directory.
|
||
{package}.mo This is the Target. It is specified as the name of
|
||
the package, for example, "foobar" with the addition
|
||
of the .mo extension.
|
||
|
||
*package-translate_example*
|
||
Let's show it all on some concrete example and translate the
|
||
"ftplugin/aap.vim" file into Russian and German.
|
||
|
||
First, let's prepare the "aap.vim" file, specifying |bindtextdomain()| and
|
||
|gettext()| function calls in it.
|
||
>
|
||
" Only do this when not done yet for this buffer
|
||
if exists("b:did_ftplugin")
|
||
finish
|
||
endif
|
||
|
||
" Don't load another plugin for this buffer
|
||
let b:did_ftplugin = 1
|
||
call bindtextdomain("aap", fnamemodify(expand("<script>"), ':p:h') .. '/../lang/')
|
||
|
||
" Reset 'formatoptions', 'comments', 'commentstring' and 'expandtab' to undo
|
||
" this plugin.
|
||
let b:undo_ftplugin = "setl fo< com< cms< et<"
|
||
|
||
" Set 'formatoptions' to break comment lines but not other lines,
|
||
" and insert the comment leader when hitting <CR> or using "o".
|
||
setlocal fo-=t fo+=croql
|
||
|
||
" Set 'comments' to format dashed lists in comments.
|
||
setlocal comments=s:#\ -,m:#\ \ ,e:#,n:#,fb:-
|
||
setlocal commentstring=#\ %s
|
||
|
||
" Expand tabs to spaces to avoid trouble.
|
||
setlocal expandtab
|
||
|
||
if (has("gui_win32") || has("gui_gtk")) && !exists("b:browsefilter")
|
||
let b:browsefilter = gettext("Aap Recipe Files (*.aap)\t*.aap\n", "aap")
|
||
if has("win32")
|
||
let b:browsefilter ..= gettext("All Files (*.*)\t*\n", "aap")
|
||
else
|
||
let b:browsefilter ..= gettext("All Files (*)\t*\n", "aap")
|
||
endif
|
||
let b:undo_ftplugin ..= " | unlet! b:browsefilter"
|
||
endif
|
||
<
|
||
Now let's create a POT file for it (example uses Windows paths):
|
||
>
|
||
cd /d f:\forkvim\src\po
|
||
(the following command must be entered in one line, here it is separated for example)
|
||
nmake.exe -f Make_mvc.mak "PLUGPACKAGE=aap"
|
||
"PO_PLUG_INPUTLIST=d:\Programs\vim\vim91\ftplugin\aap.vim"
|
||
"POT_PLUGPACKAGE_PATH=e:\project\translate\plugins"
|
||
"VIMPROG=d:\Programs\vim\vim91\vim.exe"
|
||
aap.pot
|
||
<
|
||
After the POT file of our package is created, go to the directory where we
|
||
saved it and perform the translation.
|
||
>
|
||
cd /d e:\project\translate\plugins
|
||
copy aap.pot ru.po
|
||
copy aap.pot de.po
|
||
<
|
||
We have prepared a PO file with a translation into Russian:
|
||
# Test plugins translate ~
|
||
# ~
|
||
msgid "" ~
|
||
msgstr "" ~
|
||
"Project-Id-Version: aap\n" ~
|
||
"Report-Msgid-Bugs-To: \n" ~
|
||
"POT-Creation-Date: 2024-06-23 14:58+0300\n" ~
|
||
"PO-Revision-Date: 2024-06-23 14:58+0300\n" ~
|
||
"Last-Translator: Restorer\n" ~
|
||
"Language-Team: RuVim\n" ~
|
||
"Language: ru\n" ~
|
||
"MIME-Version: 1.0\n" ~
|
||
"Content-Type: text/plain; charset=UTF-8\n" ~
|
||
"Content-Transfer-Encoding: 8bit\n" ~
|
||
|
||
#: ../../runtime/ftplugin/aap.vim:32 ~
|
||
msgid "Aap Recipe Files (*.aap)\t*.aap\n" ~
|
||
msgstr "Файлы инструкций Aap (*.aap)\t*.aap\n" ~
|
||
|
||
#: ../../runtime/ftplugin/aap.vim:34 ~
|
||
msgid "All Files (*.*)\t*\n" ~
|
||
msgstr "Все файлы (*.*)\t*\n" ~
|
||
|
||
#: ../../runtime/ftplugin/aap.vim:36 ~
|
||
msgid "All Files (*)\t*\n" ~
|
||
msgstr "Все файлы (*)\t*\n" ~
|
||
|
||
And the PO file in German:
|
||
# Test plugins translate~
|
||
#~
|
||
msgid ""~
|
||
msgstr ""~
|
||
"Project-Id-Version: aap\n"~
|
||
"Report-Msgid-Bugs-To: \n"~
|
||
"POT-Creation-Date: 2024-06-23 14:58+0300\n"~
|
||
"PO-Revision-Date: 2024-06-24 13:11+0300\n"~
|
||
"Last-Translator: Restorer\n"~
|
||
"Language-Team: German\n"~
|
||
"Language: de\n"~
|
||
"MIME-Version: 1.0\n"~
|
||
"Content-Type: text/plain; charset=UTF-8\n"~
|
||
"Content-Transfer-Encoding: 8bit\n"~
|
||
|
||
#: ../../runtime/ftplugin/aap.vim:32~
|
||
msgid "Aap Recipe Files (*.aap)\t*.aap\n"~
|
||
msgstr "Aap-Rezeptdateien (*.aap)\t*.aap\n"~
|
||
|
||
#: ../../runtime/ftplugin/aap.vim:34~
|
||
msgid "All Files (*.*)\t*\n"~
|
||
msgstr "Alle Dateien (*.*)\t*.*\n"~
|
||
|
||
#: ../../runtime/ftplugin/aap.vim:36~
|
||
msgid "All Files (*)\t*\n"~
|
||
msgstr "Alle Dateien (*)\t*\n"~
|
||
|
||
Now convert these files into MO files so that |gettext()| can display message
|
||
translations. Note that since this is not a specialized plugin package, we
|
||
will put the MO files in the "lang/" directory of the Vim editor.
|
||
Type the following commands:
|
||
>
|
||
cd /d f:\forkvim\src\po
|
||
< (the following command must be entered in one line, here it is separated for example)
|
||
For Russian: >
|
||
nmake.exe -f Make_mvc.mak "PLUGPACKAGE=aap"
|
||
"PO_PLUGPACKAGE=e:\project\translate\plugins\ru.po"
|
||
"MO_PLUGPACKAGE_PATH=d:\Programs\vim\vim91\lang\ru\LC_MESSAGES"
|
||
aap.mo
|
||
< For German: >
|
||
nmake.exe -f Make_mvc.mak "PLUGPACKAGE=aap"
|
||
"PO_PLUGPACKAGE=e:\project\translate\plugins\de.po"
|
||
"MO_PLUGPACKAGE_PATH=d:\Programs\vim\vim91\lang\de\LC_MESSAGES"
|
||
aap.mo
|
||
<
|
||
That's it, the translations are ready and you can see the plugin's messages
|
||
in your native language.
|
||
|
||
Let's also try to translate a plugin package. For example, when a package
|
||
contains several scripts containing strings that need to be translated.
|
||
For example, let's translate the "netrw" package into Japanese.
|
||
For this example, we will translate only a few lines from this package.
|
||
Let's prepare the scripts where we need to translate the message strings.
|
||
|
||
The file "autoload\netrw.vim":
|
||
>
|
||
" Load Once:
|
||
if &cp || exists("g:loaded_netrw")
|
||
finish
|
||
endif
|
||
call bindtextdomain("netrw", fnamemodify(expand("<script>"), ':p:h') .. '/../lang/')
|
||
|
||
" Check that vim has patches that netrw requires.
|
||
" Patches needed for v7.4: 1557, and 213.
|
||
" (netrw will benefit from vim's having patch#656, too)
|
||
let s:needspatches=[1557,213]
|
||
if exists("s:needspatches")
|
||
for ptch in s:needspatches
|
||
if v:version < 704 || (v:version == 704 && !has("patch".ptch))
|
||
if !exists("s:needpatch{ptch}")
|
||
unsilent echomsg gettext("***sorry*** this version of netrw requires vim v7.4 with patch#", "netrw") .. ptch
|
||
endif
|
||
let s:needpatch{ptch}= 1
|
||
finish
|
||
endif
|
||
endfor
|
||
endif
|
||
<
|
||
The file "autoload\netrwSettings.vim":
|
||
>
|
||
" Load Once:
|
||
if exists("g:loaded_netrwSettings") || &cp
|
||
finish
|
||
endif
|
||
call bindtextdomain("netrw", fnamemodify(expand("<script>"), ':p:h') .. '/../lang/')
|
||
let g:loaded_netrwSettings = "v18"
|
||
if v:version < 700
|
||
echohl WarningMsg
|
||
echo gettext("***warning*** this version of netrwSettings needs vim 7.0", "netrw")
|
||
echohl Normal
|
||
finish
|
||
endif
|
||
<
|
||
Now we will prepare a POT file for further translation of messages.
|
||
Execute the following commands:
|
||
>
|
||
cd ~/forkvim/src/po
|
||
make -f Makefile "VIMPROG=/usr/local/bin/vim" "PLUGPACKAGE=netrw" \
|
||
"POT_PLUGPACKAGE_PATH=~/project/translate/plugins" \
|
||
"PO_PLUG_INPUTLIST=../../runtime/autoload/netrw.vim
|
||
../../runtime/autoload/netrwSettings.vim" \
|
||
netrw.pot
|
||
<
|
||
Go to the directory with the POT file and make the translation:
|
||
>
|
||
cd ~/project/translate/plugins
|
||
cp ./netrw.pot ja.po
|
||
<
|
||
When we have the translation ready in the "ja.po" file:
|
||
# Test plugins translate ~
|
||
# ~
|
||
msgid "" ~
|
||
msgstr "" ~
|
||
"Project-Id-Version: netrw\n" ~
|
||
"Report-Msgid-Bugs-To: \n" ~
|
||
"POT-Creation-Date: 2024-06-23 17:14+0300\n" ~
|
||
"PO-Revision-Date: 2024-06-23 17:14+0300\n" ~
|
||
"Last-Translator: Restorer\n" ~
|
||
"Language-Team: Japanese\n" ~
|
||
"Language: ja\n" ~
|
||
"MIME-Version: 1.0\n" ~
|
||
"Content-Type: text/plain; charset=UTF-8\n" ~
|
||
"Content-Transfer-Encoding: 8bit\n" ~
|
||
|
||
#: ../../runtime/autoload/netrw.vim:51 ~
|
||
msgid "***sorry*** this version of netrw requires vim v7.4 with patch#" ~
|
||
msgstr "" ~
|
||
"***申し訳ありません***このバージョンのnetrwには、パッチ付きのvim v7.4が必要です#" ~
|
||
|
||
#: ../../runtime/autoload/netrwSettings.vim:28 ~
|
||
msgid "***warning*** this version of netrwSettings needs vim 7.0" ~
|
||
msgstr "***警告***このバージョンのnetrwSettingsにはvim7.0が必要です" ~
|
||
|
||
Convert ja.po to a MO file:
|
||
>
|
||
cd ~/forkvim/src/po
|
||
make -f Makefile "PLUGPACKAGE=netrw" \
|
||
"PO_PLUGPACKAGE=~/project/translate/plugins/ja.po" \
|
||
"MO_PLUGPACKAGE_PATH=/usr/local/share/vim/vim91/lang/ja/LC_MESSAGES" \
|
||
netrw.mo
|
||
<
|
||
Executing those steps will allow you to get translation of any third-party
|
||
plug-in packages.
|
||
|
||
Dependencies between plugins ~
|
||
*packload-two-steps*
|
||
Suppose you have two plugins that depend on the same functionality. You can
|
||
put the common functionality in an autoload directory, so that it will be
|
||
found automatically. Your package would have these files:
|
||
|
||
pack/foo/start/one/plugin/one.vim >
|
||
call foolib#getit()
|
||
< pack/foo/start/two/plugin/two.vim >
|
||
call foolib#getit()
|
||
< pack/foo/start/lib/autoload/foolib.vim >
|
||
func foolib#getit()
|
||
|
||
This works, because loading packages will first add all found directories to
|
||
'runtimepath' before sourcing the plugins.
|
||
|
||
==============================================================================
|
||
7. 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.
|
||
|
||
NOTE: In Vim9 script, if a command is written at the script level and
|
||
continues on the next line, not using the old way with a backslash for line
|
||
continuation, only the first line is printed before the debugging prompt.
|
||
|
||
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.
|
||
*>bt*
|
||
*>backtrace*
|
||
*>where*
|
||
backtrace Show the call stacktrace for current debugging session.
|
||
bt
|
||
where
|
||
*>frame*
|
||
frame N Goes to N backtrace level. + and - signs make movement
|
||
relative. E.g., ":frame +3" goes three frames up.
|
||
*>up*
|
||
up Goes one level up from call stacktrace.
|
||
*>down*
|
||
down Goes one level down from call stacktrace.
|
||
|
||
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, unless more than one command
|
||
starts with the same letter. "f" stands for "finish", use "fr" for "frame".
|
||
- 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).
|
||
*vim9-debug*
|
||
When debugging a compiled :def function, "step" will stop before every
|
||
executed line, not every single instruction. Thus it works mostly like a not
|
||
compiled function. Access to local variables is limited you can use: >
|
||
echo varname
|
||
But not much else.
|
||
When executing a command that is not a specific bytecode instruction but
|
||
executed like a normal Ex command, "step" will stop once in the compiled
|
||
context, where local variables can be inspected, and once just before
|
||
executing the command.
|
||
|
||
In a :def function variables that haven't been declared yet cannot be
|
||
inspected. Variables that have been declared can be inspected, also when the
|
||
block they were declared in has finished. In commands this would not be
|
||
possible, thus is slightly misleading (but can be useful).
|
||
|
||
The backtrace shows the hierarchy of function calls, e.g.:
|
||
>bt ~
|
||
3 function One[3] ~
|
||
2 Two[3] ~
|
||
->1 Three[3] ~
|
||
0 Four ~
|
||
line 1: let four = 4 ~
|
||
|
||
The "->" points to the current frame. Use "up", "down" and "frame N" to
|
||
select another frame.
|
||
|
||
In the current frame you can evaluate the local function variables. There is
|
||
no way to see the command at the current line yet.
|
||
|
||
|
||
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.
|
||
|
||
:breaka[dd] expr {expression}
|
||
Sets a breakpoint, that will break whenever the {expression}
|
||
evaluates to a different value. Example: >
|
||
:breakadd expr g:lnum
|
||
< Will break, whenever the global variable lnum changes.
|
||
|
||
Errors in evaluation are suppressed, you can use the name of a
|
||
variable that does not exist yet. This also means you will
|
||
not notice anything if the expression has a mistake.
|
||
|
||
Note if you watch a |script-variable| this will break
|
||
when switching scripts, since the script variable is only
|
||
valid in the script where it has been defined and if that
|
||
script is called from several other scripts, this will stop
|
||
whenever that particular variable will become visible or
|
||
inaccessible again.
|
||
|
||
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". However, for local functions the script-specific prefix such
|
||
as "<SNR>99_" is ignored to make it easier to match script-local functions
|
||
without knowing the ID of the script.
|
||
|
||
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.
|
||
|
||
==============================================================================
|
||
8. 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 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 in more builds.
|
||
|
||
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 or when
|
||
a `:profile stop` or `:profile dump` command is invoked.
|
||
"~/" and environment variables in {fname} will be expanded.
|
||
If {fname} already exists it will be silently overwritten.
|
||
The variable |v:profiling| is set to one.
|
||
|
||
:prof[ile] stop
|
||
Write the collected profiling information to the logfile and
|
||
stop profiling. You can use the `:profile start` command to
|
||
clear the profiling statistics and start profiling again.
|
||
|
||
:prof[ile] pause
|
||
Stop profiling until the next `:profile continue` command.
|
||
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.
|
||
|
||
:prof[ile] dump
|
||
Write the current state of profiling to the logfile
|
||
immediately. After running this command, Vim continues to
|
||
collect the profiling statistics.
|
||
|
||
:profd[el] ... *:profd* *:profdel*
|
||
Stop profiling for the arguments specified. See |:breakdel|
|
||
for the arguments. Examples: >
|
||
profdel func MyFunc
|
||
profdel file MyScript.vim
|
||
profdel here
|
||
|
||
You must always start with a ":profile start fname" command. The resulting
|
||
file is written when Vim exits. For example, to profile one specific
|
||
function: >
|
||
profile start /tmp/vimprofile
|
||
profile func MyFunc
|
||
|
||
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(), or
|
||
clock_gettime() if available, system function. The accuracy ranges from
|
||
1/100 second to nanoseconds. With clock_gettime() the times are displayed in
|
||
nanoseconds, otherwise microseconds. You can use `has("prof_nsec")`.
|
||
|
||
- 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:noet:ft=help:norl:
|