Creating New Commands in Vim: Key Mappings and Autocommands

*usr_40.txt* Nvim 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 <F1>, have no predefined meaning in Vim, these are good choices to map. Example: > :map <F2> GoDate: <Esc>:read !date<CR>kJ 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 <Esc> 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 <CR> 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 <F2> <CR>Date: <Esc>:read !date<CR>kJ It looks a lot like the mapping for <F2> in Normal mode, only the start is different. The <F2> 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 <F7> so that the command d<F7> deletes a C program block (text enclosed in curly braces, {}). Similarly y<F7> would yank the program block into the unnamed register. Therefore, what you need to do is to define <F7> to select the current program block. You can do this with the following command: > :omap <F7> a{ This causes <F7> 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)<CR> ~ v <F2> :s/^/> /<CR>:noh<CR>`` ~ n <F2> :.,$s/^/> /<CR>:noh<CR>`` ~ <xHome> <Home> <xEnd> <End> The first column of the list shows in which mode the mapping is effective. This is "n" for Normal mode, "i" for Insert

This section of the Vim user manual focuses on extending Vim's functionality by creating new commands. It covers key mappings, which allow users to translate one sequence of keystrokes into another, and defining command-line commands. It also introduces autocommands for automated command execution. The chapter details how to map keys in different modes (Normal, Insert, Visual, Operator-pending, and Command-line) and provides examples of creating mappings for various tasks, such as inserting the date or deleting/yanking a C program block. The process for listing currently defined mappings is also explained.