Edit: /usr/share/vim/vim82/doc/usr_40.txt (23195B)
*usr_40.txt* For Vim version 8.2. Last change: 2020 Sep 02
VIM USER MANUAL - by Bram Moolenaar
Make new commands
Vim is an extensible editor. You can take a sequence of commands you use
often and turn it into a new command. Or redefine an existing command.
Autocommands make it possible to execute commands automatically.
|40.1| Key mapping
|40.2| Defining command-line commands
|40.3| Autocommands
Next chapter: |usr_41.txt| Write a Vim script
Previous chapter: |usr_32.txt| The undo tree
Table of contents: |usr_toc.txt|
==============================================================================
*40.1* Key mapping
A simple mapping was explained in section |05.3|. The principle is that one
sequence of key strokes is translated into another sequence of key strokes.
This is a simple, yet powerful mechanism.
The simplest form is that one key is mapped to a sequence of keys. Since
the function keys, except
, have no predefined meaning in Vim, these are
good choices to map. Example: >
:map GoDate: :read !datekJ
This shows how three modes are used. After going to the last line with "G",
the "o" command opens a new line and starts Insert mode. The text "Date: " is
inserted and takes you out of insert mode.
Notice the use of special keys inside <>. This is called angle bracket
notation. You type these as separate characters, not by pressing the key
itself. This makes the mappings better readable and you can copy and paste
the text without problems.
The ":" character takes Vim to the command line. The ":read !date" command
reads the output from the "date" command and appends it below the current
line. The is required to execute the ":read" command.
At this point of execution the text looks like this:
Date: ~
Fri Jun 15 12:54:34 CEST 2001 ~
Now "kJ" moves the cursor up and joins the lines together.
To decide which key or keys you use for mapping, see |map-which-keys|.
MAPPING AND MODES
The ":map" command defines remapping for keys in Normal mode. You can also
define mappings for other modes. For example, ":imap" applies to Insert mode.
You can use it to insert a date below the cursor: >
:imap Date: :read !datekJ
It looks a lot like the mapping for in Normal mode, only the start is
different. The mapping for Normal mode is still there. Thus you can map
the same key differently for each mode.
Notice that, although this mapping starts in Insert mode, it ends in Normal
mode. If you want it to continue in Insert mode, append an "a" to the
mapping.
Here is an overview of map commands and in which mode they work:
:map Normal, Visual and Operator-pending
:vmap Visual
:nmap Normal
:omap Operator-pending
:map! Insert and Command-line
:imap Insert
:cmap Command-line
Operator-pending mode is when you typed an operator character, such as "d" or
"y", and you are expected to type the motion command or a text object. Thus
when you type "dw", the "w" is entered in operator-pending mode.
Suppose that you want to define so that the command d deletes a C
program block (text enclosed in curly braces, {}). Similarly y would yank
the program block into the unnamed register. Therefore, what you need to do
is to define to select the current program block. You can do this with
the following command: >
:omap a{
This causes to perform a select block "a{" in operator-pending mode, just
like you typed it. This mapping is useful if typing a { on your keyboard is a
bit difficult.
LISTING MAPPINGS
To see the currently defined mappings, use ":map" without arguments. Or one
of the variants that include the mode in which they work. The output could
look like this:
_g :call MyGrep(1) ~
v :s/^/> /:noh`` ~
n :.,$s/^/> /:noh`` ~
The first column of the list shows in which mode the mapping is effective.
This is "n" for Normal mode, "i" for Insert mode, etc. A blank is used for a
mapping defined with ":map", thus effective in both Normal and Visual mode.
One useful purpose of listing the mapping is to check if special keys in <>
form have been recognized (this only works when color is supported). For
example, when is displayed in color, it stands for the escape character.
When it has the same color as the other text, it is five characters.
REMAPPING
The result of a mapping is inspected for other mappings in it. For example,
the mappings for above could be shortened to: >
:map G
:imap
:map oDate: :read !datekJ
For Normal mode is mapped to go to the last line, and then behave like
was pressed. In Insert mode stops Insert mode with and then
also uses . Then is mapped to do the actual work.
Suppose you hardly ever use Ex mode, and want to use the "Q" command to format
text (this was so in old versions of Vim). This mapping will do it: >
:map Q gq
But, in rare cases you need to use Ex mode anyway. Let's map "gQ" to Q, so
that you can still go to Ex mode: >
:map gQ Q
What happens now is that when you type "gQ" it is mapped to "Q". So far so
good. But then "Q" is mapped to "gq", thus typing "gQ" results in "gq", and
you don't get to Ex mode at all.
To avoid keys to be mapped again, use the ":noremap" command: >
:noremap gQ Q
Now Vim knows that the "Q" is not to be inspected for mappings that apply to
it. There is a similar command for every mode:
:noremap Normal, Visual and Operator-pending
:vnoremap Visual
:nnoremap Normal
:onoremap Operator-pending
:noremap! Insert and Command-line
:inoremap Insert
:cnoremap Command-line
RECURSIVE MAPPING
When a mapping triggers itself, it will run forever. This can be used to
repeat an action an unlimited number of times.
For example, you have a list of files that contain a version number in the
first line. You edit these files with "vim *.txt". You are now editing the
first file. Define this mapping: >
:map ,, :s/5.1/5.2/:wnext,,
Now you type ",,". This triggers the mapping. It replaces "5.1" with "5.2"
in the first line. Then it does a ":wnext" to write the file and edit the
next one. The mapping ends in ",,". This triggers the same mapping again,
thus doing the substitution, etc.
This continues until there is an error. In this case it could be a file
where the substitute command doesn't find a match for "5.1". You can then
make a change to insert "5.1" and continue by typing ",," again. Or the
":wnext" fails, because you are in the last file in the list.
When a mapping runs into an error halfway, the rest of the mapping is
discarded. CTRL-C interrupts the mapping (CTRL-Break on MS-Windows).
DELETE A MAPPING
To remove a mapping use the ":unmap" command. Again, the mode the unmapping
applies to depends on the command used:
:unmap Normal, Visual and Operator-pending
:vunmap Visual
:nunmap Normal
:ounmap Operator-pending
:unmap! Insert and Command-line
:iunmap Insert
:cunmap Command-line
There is a trick to define a mapping that works in Normal and Operator-pending
mode, but not in Visual mode. First define it for all three modes, then
delete it for Visual mode: >
:map /--->
:vunmap
Notice that the five characters "" stand for the single key CTRL-A.
To remove all mappings use the |:mapclear| command. You can guess the
variations for different modes by now. Be careful with this command, it can't
be undone.
SPECIAL CHARACTERS
The ":map" command can be followed by another command. A | character
separates the two commands. This also means that a | character can't be used
inside a map command. To include one, use (five characters). Example:
>
:map :write !checkin %:S
The same problem applies to the ":unmap" command, with the addition that you
have to watch out for trailing white space. These two commands are different:
>
:unmap a | unmap b
:unmap a| unmap b
The first command tries to unmap "a ", with a trailing space.
When using a space inside a mapping, use (seven characters): >
:map W
This makes the spacebar move a blank-separated word forward.
It is not possible to put a comment directly after a mapping, because the "
character is considered to be part of the mapping. You can use |", this
starts a new, empty command with a comment. Example: >
:map W| " Use spacebar to move forward a word
MAPPINGS AND ABBREVIATIONS
Abbreviations are a lot like Insert mode mappings. The arguments are handled
in the same way. The main difference is the way they are triggered. An
abbreviation is triggered by typing a non-word character after the word. A
mapping is triggered when typing the last character.
Another difference is that the characters you type for an abbreviation are
inserted in the text while you type them. When the abbreviation is triggered
these characters are deleted and replaced by what the abbreviation produces.
When typing the characters for a mapping, nothing is inserted until you type
the last character that triggers it. If the 'showcmd' option is set, the
typed characters are displayed in the last line of the Vim window.
An exception is when a mapping is ambiguous. Suppose you have done two
mappings: >
:imap aa foo
:imap aaa bar
Now, when you type "aa", Vim doesn't know if it should apply the first or the
second mapping. It waits for another character to be typed. If it is an "a",
the second mapping is applied and results in "bar". If it is a space, for
example, the first mapping is applied, resulting in "foo", and then the space
is inserted.
ADDITIONALLY...
The