: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 init.vim file, you can
source it from your init.vim 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.
:source_crnl W15
Windows: 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.
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 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
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.
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 "~/.local/share/nvim/site" directory
and you want to add a package from a zip archive "/tmp/foopack.zip":
% mkdir -p ~/.local/share/nvim/site/pack/foo
% cd ~/.local/share/nvim/site/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 ~/.local/share/nvim/site:
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.
In the example Vim will find "pack/foo/start/foobar/plugin/foo.vim" and adds
"~/.local/share/nvim/site/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 ~/.local/share/nvim/site/pack/foo/start/foobar
% cd ~/.local/share/nvim/site/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
~/.local/share/nvim/site/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.
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 chose what they include or not. Or you can decide to use one
package with optional plugins, and tell the user to add the ones he wants 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
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 ~/.local/share/nvim/site/pack/myfoobar
cd ~/.local/share/nvim/site/pack/myfoobar
git clone https://github.com/you/foobar.git
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.
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 his
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
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.
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) 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.
>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).
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 init.vim
: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.