《Learning the vi editor》

projl

You can combine :read with a call to UNIX, to read the results of a
UNIX command into your file. As a very simple example:

:r !date

will read in the system's date information into the text of your file.
By preceding the :r command with a line address, you can read the
result of the command in at any desired point in your file. By
default, it will appear after the current line.

Suppose you are editing a file and want to read in four phone
numbers from a file called phone, but in alphabetical order. phone
reads:

Willing, Sue 333-4444
Walsh, Linda 555-6666
Quercia, Valerie 777-8888
Dougherty, Nancy 999-0000

The command:

:r !sort phone

reads in the contents of phone after they have been passed through
the sort filter:

Dougherty, Nancy 999-0000
Quercia, Valerie 777-8888
Walsh, Linda 555-6666
Willing, Sue 333-4444

Suppose you are editing a file and want to insert text from another
file in the directory, but you can't remember the new file's name.
You could perform this task the long way: exit your file, give the ls
command, note the correct filename, reenter your file, and search
for your place.

Or you could do the task in fewer steps:

Keystrokes Results
:!ls
Display a list of files in the current directory. Note the correct
filename. Press RETURN to continue editing.
:r
newfile

projl

Read in the new file.
7.2.1 Filtering Text Through a Command
You can also send a block of text as standard input to a UNIX
command. The output from this command replaces the block of text
in the buffer. You can filter text through a command from either ex
or vi. The main difference between the two methods is that you
indicate the block of text with line addresses in ex and with text
objects (movement commands) in vi.

7.2.1.1 Filtering text with ex
The first example demonstrates how to filter text with ex. Assume
that the list of names in the preceding example, instead of being
contained in a separate file called phone, is already contained in the
current file on lines 96 through 99. You simply type the addresses
of the lines you want to filter, followed by an exclamation mark and
the UNIX command to be executed. For example, the command:

:96,99!sort

will pass lines 96 through 99 through the sort filter and replace
those lines with the output of sort.

7.2.1.2 Filtering text with vi
In vi, text is filtered through a UNIX command by typing an
exclamation mark followed by any of vi's movement keystrokes that
indicate a block of text, and then by the UNIX command line to be
executed. For example:

!)command

will pass the next sentence through command.

There are a few unusual features about how vi acts when you use
this feature:

鈥

projl

precede either the exclamation mark or the text object. (For
example, both !10+ and 10!+ would indicate the next ten
lines.) Objects such as w do not work unless enough of them
are specified so as to exceed a single line. You can also use a
slash (/) followed by a pattern and a carriage return to
specify the object. This takes the text up to the pattern as
input to the command.

鈥

projl

!)

An exclamation mark appears on the last line to prompt you for the
UNIX command. The ) indicates that a sentence is the unit of text to
be filtered.

tr '[a-z]'
'[A-Z]'


Enter the UNIX command and press RETURN. The input is replaced
by the output.

To repeat the previous command, the syntax is:

! object !

It is sometimes useful to send sections of a coded document to nroff
to be replaced by formatted output. (Or when editing electronic
mail, you might use the fmt program to "beautify" your text before
sending the message.) Remember that the "original" input is
replaced by the output. Fortunately, if there is a mistake, such as
an error message being sent instead of the expected output, you
can undo the command and restore the lines.

7.3 Saving Commands
Often you type the same long phrases over and over in a file. vi and
ex have a number of different ways of saving long sequences of
commands, both in command mode and in insert mode. When you
call up one of these saved sequences to execute it, all you do is
type a few characters (or even only one), and the entire sequence is
executed as if you had entered the whole sequence of commands
one by one.

7.3.1 Word Abbreviation
You can define abbreviations that vi will automatically expand into
the full text whenever you type the abbreviation in insert mode. To
define an abbreviation, use the ex command:

:ab abbr phrase

projl

abbr is an abbreviation for the specified phrase. The sequence of
characters that make up the abbreviation will be expanded in insert
mode only if you type it as a full word; abbr will not be expanded
within a word.

Suppose in the file practice you want to enter text that contains a
frequently recurring phrase such as a difficult product or company
name. The command:

:ab imrc International Materials Research Center

abbreviates International Materials Research Center to the initials
imrc. Now whenever you type imrc in insert mode, imrc expands to

the full text.
Keystrokes Results
ithe imrc
Abbreviations expand as soon as you press a non-alphanumeric
character (e.g., punctuation), a space, a carriage return, or ESC
(returning to command mode). When you are choosing
abbreviations, choose combinations of characters that don't
ordinarily occur while you are typing text. If you create an
abbreviation that ends up expanding in places where you don't want
it to, you can disable the abbreviation by typing:

:unab abbr

To list your currently defined abbreviations, type:

:ab

The characters that compose your abbreviation cannot also appear
at the end of your phrase. For example, if you issue the command:

:ab PG This movie is rated PG

you'll get the message "No tail recursion," and the abbreviation
won't be set. The message means that you have tried to define
something that will expand itself repeatedly, creating an infinite
loop. If you issue the command:

:ab PG the PG rating system

you may or may not produce an infinite loop, but in either case you
won't get a warning message. For example, when the above
command was tested on a System V version of UNIX, the expansion
worked. Circa 1990 on a Berkeley version, the abbreviation
expanded repeatedly, like this:

projl

the the the the the ...

until a memory error occurred and vi quit.
When tested, we obtained the following results on these vi versions:


Solaris 2.6 vi


The tail recursive version is not allowed, while the version
with the name in the middle of the expansion only expands
once.

nvi 1.79

Both versions exceed an internal expansion limit, the
expansion stops, and nvi produces an error message.

elvis 2.0

The tail recursive version runs infinitely until the editor is
interrupted. The version with the name in the middle
eventually stops expanding, but without any error message.

vim 5.0 and 5.1

Both forms are detected and only expand once.

vile 7.4 and 8.0

Both forms are detected and only expand once.

We recommend that you avoid repeating your abbreviation as part
of the defined phrase.

7.3.2 Using the map Command
While you're editing, you may find that you are using a command
sequence frequently, or you may occasionally use a very complex
command sequence. To save yourself keystrokes, or the time that it
takes to remember the sequence, you can assign the sequence to
an unused key by using the map command.

The map command acts a lot like ab except that you define a macro
for vi's command mode instead of for insert mode.

:map x sequence

Define character x as a sequence of editing commands.

projl

:unmap x

Disable the sequence defined for x.

:map

List the characters that are currently mapped.

Before you can start creating your own maps, you need to know the
keys not used in command mode that are available for user-defined
commands:

Letters

g K q V v

Control keys

^A ^K ^O ^W ^X

Symbols

_ * \ =


The = is used by vi if Lisp mode is set, and to do
text formatting by several of the clones. In many
modern versions of vi, the _ is equivalent to the ^
command, and elvis and vim have a "visual mode"
that uses the v, V, and ^V keys. The moral is to test
your version carefully.

Depending on your terminal, you may also be able to associate map
sequences with special function keys.

With maps you can create simple or complex command sequences.
As a simple example, you could define a command to reverse the
order of words. In vi, with the cursor as shown:

you can the scroll page

the sequence to put the after scroll would be dwelp: delete word,
dw; move to the end of next word, e; move one space to the right,
l; put the deleted word there, p. Saving this sequence:

:map v dwelp

projl

enables you to reverse the order of two words at any time in the
editing session with the single keystroke v.

7.3.3 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 CTRL-V. The keystroke ^V appears in the
map as the ^ character. Characters following the ^V also do not
appear as you expect. For example, a carriage return 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 is to type:

:map CTRL-A sequence

There are, however, three control characters that must be escaped
with a ^V. They are ^T, ^W, and ^X. 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 or a substitution command. For example, the
abbreviation:

:ab 123 one^Mtwo^Mthree

expands to this:

one
two
three

(Here we show the sequence CTRL-V RETURN as ^M, the way it
would appear on your screen.)

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

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

projl

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

Unfortunately, one character always has special meaning in ex
commands, even if you try to quote it with CTRL-V. Recall that the
vertical bar (|) has special meaning as a separator of multiple ex
commands. You cannot use a vertical bar in insert mode maps.

Now that you've seen how to use CTRL-V to protect certain keys
inside ex commands, you're ready to define some powerful map
sequences.

7.3.4 Complex Mapping Example
Assume that you have a glossary with entries like this:

map - an ex command which allows you to associatea complex command sequence with a single key.

You would like to convert this glossary list to troff format, so that it
looks like this:

.IP "map" 10 nAn ex command...

The best way to define a complex map is to do the edit once
manually, writing down each keystroke that you have to type. Then
recreate these keystrokes as a map. You want to:

1. Insert the MS macro for an indented paragraph at the
beginning of the line. Insert the first quotation mark as well
(I.IP ").
2. Press ESC to terminate insert mode.
3. Move to the end of the first word (e) and add a second
quotation mark, followed by a space and the size of the indent
(a" 10n).
4. Press RETURN to insert a new line.
5. Press ESC to terminate insert mode.
6. Remove the hyphen and two surrounding spaces (3x) and
capitalize the next word (~).
That will be quite an editing chore if you have to repeat it more
than just a few times.

With :map you can save the entire sequence so that it can be re-
executed with a single keystroke:

projl

:map g I.IP "^[ea" 10n^M^[3x~

Note that you have to "quote" both the ESC and RETURN characters
with CTRL-V. ^[ is the sequence that appears when you type CTRLV
followed by ESC. ^M is the sequence shown when you type CTRL-V
RETURN.

Now, simply typing g will perform the entire series of edits. At a
slow baud rate you can actually see the edits happening
individually. At a fast baud rate it will seem to happen by magic.

Don't be discouraged if your first attempt at key mapping fails. A
small error in defining the map can give very different results from
the ones you expect. Type u to undo the edit, and try again.

7.3.5 More Examples of Mapping Keys
These examples will give you an idea of the clever shortcuts
possible when defining keyboard maps:

1. Add text whenever you move to the end of a word:
:map e ea

Most of the time, the only reason you want to move to the
end of a word is to add text. This map sequence puts you in
insert mode automatically. Note that the mapped key, e, has
meaning in vi. You're allowed to map a key that is already
used by vi, but the key's normal function will be unavailable
as long as the map is in effect. This isn't so bad in this case,
since the E command is often identical to e.

2. Transpose two words:
:map K dwElp

We discussed this sequence earlier in the chapter, but now
you need to use E (assume here, and in the remaining
examples, that the e command is mapped to ea). Remember
that the cursor begins on the first of the two words.
Unfortunately, because of the l command, this sequence (and
the earlier version) doesn't work if the two words are at the
end of a line: during the sequence, the cursor ends up at the
end of the line, and l cannot move further right. Here's a
better solution:

:map K dwwP