*usr_40.txt* For Vim version 7.3. Last change: 2006 Jun 21 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 % 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