Basic Mapping
If there's one feature of Vimscript that will let you bend Vim to your will more than any other, it's the ability to map keys. Mapping keys lets you tell Vim:
When I press this key, I want you to do this stuff instead of whatever you would normally do.
We're going to start off by mapping keys in normal mode. We'll talk about how to map keys in insert and other modes in the next chapter.
Type a few lines of text into a file, then run:
:map - x
Put your cursor somewhere in the text and press -
. Notice how Vim deleted the character under the cursor, just like if you had pressed x
.
We already have a key for "delete the character under the cursor", so let's change that mapping to something slightly more useful. Run this command:
:map - dd
Now put your cursor on a line somewhere and press -
again. This time Vim deletes the entire line, because that's what dd
does.
Special Characters
You can use <keyname>
to tell Vim about special keys. Try running this command:
:map <space> viw
Put your cursor on a word in your text and press the space bar. Vim will visually select the word.
You can also map modifier keys like Ctrl and Alt. Run this:
:map <c-d> dd
Now pressing Ctrl+d
on your keyboard will run dd
.
Commenting
Remember in the first lesson where we talked about comments? Mapping keys is one of the places where Vim comments don't work. Try running this command:
:map <space> viw " Select word
If you try pressing space now, something horrible will almost certainly happen. Why?
When you press the space bar now, Vim thinks you want it to do what viw<space>"<space>Select<space>word
would do. Obviously this isn't what we want.
If you look closely at the effect of this mapping you might notice something strange. Take a few minutes to try to figure out exactly what happens when you use it, and why that happens.
Don't worry if you don't get it right away -- we'll talk about it more soon.
Strict Mapping
Get ready, because things are about to get a little wild.
So far we've used map
, nmap
, vmap
, and imap
to create key mappings that will save time. These work, but they have a downside. Run the following commands:
:nmap - dd :nmap \ -
Now try pressing \
(in normal mode). What happens?
When you press \
Vim sees the mapping and says "I should run -
instead". But we've already mapped -
to do something else! Vim sees that and says "oh, now I need to run dd
", and so it deletes the current line.
When you map keys with these commands Vim will take other mappings into account. This may sound like a good thing at first but in reality it's pure evil. Let's talk about why, but first remove those mappings by running the following commands:
:nunmap - :nunmap \
Recursion
Run this command:
:nmap dd O<esc>jddk
At first glance it might look like this would map dd
to:
- Open a new line above this one.
- Exit insert mode.
- Move back down.
- Delete the current line.
- Move up to the blank line just created.
Effectively this should "clear the current line". Try it.
Vim will seem to freeze when you press dd
. If you press <c-c>
you'll get Vim back, but there will be a ton of empty lines in your file! What happened?
This mapping is actually recursive! When you press dd
, Vim says:
-
dd
is mapped, so perform the mapping.- Open a line.
- Exit insert mode.
- Move down a line.
-
dd
is mapped, so perform the mapping.- Open a line.
- Exit insert mode.
- Move down a line.
-
dd
is mapped, so perform the mapping, and so on.
This mapping can never finish running! Go ahead and remove this terrible thing with the following command:
:nunmap dd
Side Effects
One downside of the *map
commands is the danger of recursing. Another is that their behavior can change if you install a plugin that maps keys they depend on.
When you install a new Vim plugin there's a good chance that you won't use and memorize every mapping it creates. Even if you do, you'd have to go back and look through your ~/.vimrc
file to make sure none of your custom mappings use a key that the plugin has mapped.
This would make installing plugins tedious and error-prone. There must be a better way.
Nonrecursive Mapping
Vim offers another set of mapping commands that will not take mappings into account when they perform their actions. Run these commands:
:nmap x dd :nnoremap \ x
Now press \
and see what happens.
When you press \
Vim ignores the x
mapping and does whatever it would do for x
by default. Instead of deleting the current line, it deletes the current character.
Each of the *map
commands has a *noremap
counterpart that ignores other mappings: noremap
,nnoremap
, vnoremap
, and inoremap
.
When should you use these nonrecursive variants instead of their normal counterparts?
Always.
No, seriously, always.
Using a bare *map
is just asking for pain down the road when you install a plugin or add a new custom mapping. Save yourself the trouble and type the extra characters to make sure it never happens.
Exercises
Convert all the mappings you added to your ~/.vimrc
file in the previous chapters to their nonrecursive counterparts.
Read :help unmap
.