Protecting Keys from Interpretation by ex (Unix Power Tools, 3rd Edition)

18.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). After CTRL-v, a carriage return appears as ^M, escape as ^[, backspace as ^H, and so on.

On the other hand, if you want to map a control character, in most cases you can just hold down the CTRL key and press the letter key at the same time. For example, to map ^A (CTRL-a), simply 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 as follows:

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.

The characters for interrupting jobs (Section 24.11) and stopping jobs (Section 23.1).

So, 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 (Section 17.23) 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 to separate 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! (Section 18.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 (Section 18.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}

--LL, DG, and JP, from Learning the vi Editor (O'Reilly, 1998)