31.6 Protecting Keys from Interpretation by ex

Note that when defining a map, you cannot simply type certain keys, such as RETURN, ESC, BACKSPACE, and DELETE as part of the command to be mapped, because these keys already have meaning within ex. If you want to include one of these keys as part of the command sequence, you must escape the normal meaning by preceding the key with ^V ( CTRL-v). A carriage return after CTRL-v appears as ^M, escape as ^[, backspace as ^H, and so on.

On the other hand, if you want to use a control character as the character to be mapped, in most cases all you have to do is hold down the CTRL key and press the letter key at the same time. So, for example, all you need to do in order to map ^A (CTRL-a) is to type:

:map [CTRL-a] sequence

There are, however, a few other control characters that must be escaped with a ^V. One is ^T. The others are:

• The characters that your account uses for erasing parts of the input you type at a command line, ^W for erasing words and ^U for erasing lines (see article 9.2).

• The characters for interrupting jobs (38.9) and stopping jobs (12.8).

So, for example, if you want to map ^T, you must type:

:map [CTRL-v] [CTRL-t] sequence

The use of CTRL-v applies to any ex command, not just a map command. This means that you can type a carriage return in an abbreviation (30.31) or a substitution command. For example, the abbreviation:

:ab 123 one^Mtwo^Mthree

expands to this:

one
two
three

(The sequence [CTRL-v] [RETURN] is shown as it appears on your screen, ^M.)

You can also add lines globally at certain locations. The command:

:g/^Section/s//As you recall, in^M&/

inserts a phrase on a separate line before any line beginning with the word Section. The & restores the search pattern.

The vertical bar (|) is used as a separator of multiple ex commands; it's especially difficult to quote. Because a map is interpreted when it's stored and again when it's used, you need enough CTRL-v characters to protect the vertical bar from each interpretation. You also need to protect stored CTRL-v characters by adding a CTRL-v before each one! The worst case is a text-input mode map (map! (31.2))-it needs three CTRL-v characters, which means you need to type six CTRL-v characters before you type the vertical bar. For example, the following map will make your function key F1 (31.2) insert the string {x|y}:

map! #1 {x^V^V^V|y}

If you ask for a list of text-input mode maps, you should see a single stored CTRL-v:

:map!
f1  ^[OP   {x^V|y}