Vim documentation: usr_10

*usr_10.txt*	For Vim version 7.1b.  Last change: 2006 Nov 05

		     VIM USER MANUAL - by Bram Moolenaar

			     Making big changes


In chapter 4 several ways to make small changes were explained.  This chapter
goes into making changes that are repeated or can affect a large amount of
text.  The Visual mode allows doing various things with blocks of text.  Use
an external program to do really complicated things.

|10.1|	Record and playback commands
|10.2|	Substitution
|10.3|	Command ranges
|10.4|	The global command
|10.5|	Visual block mode
|10.6|	Reading and writing part of a file
|10.7|	Formatting text
|10.8|	Changing case
|10.9|	Using an external program

     Next chapter: |usr_11.txt|  Recovering from a crash
 Previous chapter: |usr_09.txt|  Using the GUI
Table of contents: |usr_toc.txt|

==============================================================================

*10.1*	Record and playback commands

The "." command repeats the preceding change.  But what if you want to do
something more complex than a single change?  That's where command recording
comes in.  There are three steps:

1. The "q{register}" command starts recording keystrokes into the register
   named {register}.  The register name must be between a and z.
2. Type your commands.
3. To finish recording, press q (without any extra character).

You can now execute the macro by typing the command "@{register}".

Take a look at how to use these commands in practice.  You have a list of
filenames that look like this:

	stdio.h 
	fcntl.h 
	unistd.h 
	stdlib.h 

And what you want is the following:

	#include "stdio.h" 
	#include "fcntl.h" 
	#include "unistd.h" 
	#include "stdlib.h" 

You start by moving to the first character of the first line.  Next you
execute the following commands:

	qa			Start recording a macro in register a.
	^			Move to the beginning of the line.
	i#include "<Esc>	Insert the string #include " at the beginning
				of the line.
	$			Move to the end of the line.
	a"<Esc>			Append the character double quotation mark (")
				to the end of the line.
	j			Go to the next line.
	q			Stop recording the macro.

Now that you have done the work once, you can repeat the change by typing the
command "@a" three times.
   The "@a" command can be preceded by a count, which will cause the macro to
be executed that number of times.  In this case you would type:

	3@a


MOVE AND EXECUTE

You might have the lines you want to change in various places.  Just move the
cursor to each location and use the "@a" command.  If you have done that once,
you can do it again with "@@".  That's a bit easier to type.  If you now
execute register b with "@b", the next "@@" will use register b.
   If you compare the playback method with using ".", there are several
differences.  First of all, "." can only repeat one change.  As seen in the
example above, "@a" can do several changes, and move around as well.
Secondly, "." can only remember the last change.  Executing a register allows
you to make any changes and then still use "@a" to replay the recorded
commands.  Finally, you can use 26 different registers.  Thus you can remember
26 different command sequences to execute.


USING REGISTERS

The registers used for recording are the same ones you used for yank and
delete commands.  This allows you to mix recording with other commands to
manipulate the registers.
   Suppose you have recorded a few commands in register n.  When you execute
this with "@n" you notice you did something wrong.  You could try recording
again, but perhaps you will make another mistake.  Instead, use this trick:

	G			Go to the end of the file.
	o<Esc>			Create an empty line.
	"np			Put the text from the n register.  You now see
				the commands you typed as text in the file.
	{edits}			Change the commands that were wrong.  This is
				just like editing text.
	0			Go to the start of the line.
	"ny$			Yank the corrected commands into the n
				register.
	dd			Delete the scratch line.

Now you can execute the corrected commands with "@n".  (If your recorded
commands include line breaks, adjust the last two items in the example to
include all the lines.)


APPENDING TO A REGISTER

So far we have used a lowercase letter for the register name.  To append to a
register, use an uppercase letter.
   Suppose you have recorded a command to change a word to register c.  It
works properly, but you would like to add a search for the next word to
change.  This can be done with:

	qC/word<Enter>q

You start with "qC", which records to the c register and appends.  Thus
writing to an uppercase register name means to append to the register with
the same letter, but lowercase.

This works both with recording and with yank and delete commands.  For
example, you want to collect a sequence of lines into the a register.  Yank
the first line with:

	"aY

Now move to the second line, and type:

	"AY

Repeat this command for all lines.  The a register now contains all those
lines, in the order you yanked them.

==============================================================================

*10.2*	Substitution						*find-replace*

The ":substitute" command enables you to perform string replacements on a
whole range of lines.  The general form of this command is as follows:

	:[range]substitute/from/to/[flags]

This command changes the "from" string to the "to" string in the lines
specified with [range].  For example, you can change "Professor" to "Teacher"
in all lines with the following command:

	:%substitute/Professor/Teacher/
 
	Note:
	The ":substitute" command is almost never spelled out completely.
	Most of the time, people use the abbreviated version ":s".  From here
	on the abbreviation will be used.

The "%" before the command specifies the command works on all lines.  Without
a range, ":s" only works on the current line.  More about ranges in the next
section |10.3|.

By default, the ":substitute" command changes only the first occurrence on
each line.  For example, the preceding command changes the line:

	Professor Smith criticized Professor Johnson today. 

to:

	Teacher Smith criticized Professor Johnson today. 

To change every occurrence on the line, you need to add the g (global) flag.
The command:

	:%s/Professor/Teacher/g

results in (starting with the original line):

	Teacher Smith criticized Teacher Johnson today. 

Other flags include p (print), which causes the ":substitute" command to print
out the last line it changes.  The c (confirm) flag tells ":substitute" to ask
you for confirmation before it performs each substitution.  Enter the
following:

	:%s/Professor/Teacher/c

Vim finds the first occurrence of "Professor" and displays the text it is
about to change.  You get the following prompt:

	replace with Teacher (y/n/a/q/l/^E/^Y)?

At this point, you must enter one of the following answers:

	y		Yes; make this change.
	n		No; skip this match.
	a		All; make this change and all remaining ones without
			further confirmation.
	q		Quit; don't make any more changes.
	l		Last; make this change and then quit.
	CTRL-E		Scroll the text one line up.
	CTRL-Y		Scroll the text one line down.


The "from" part of the substitute command is actually a pattern.  The same
kind as used for the search command.  For example, this command only
substitutes "the" when it appears at the start of a line:

	:s/^the/these/

If you are substituting with a "from" or "to" part that includes a slash, you
need to put a backslash before it.  A simpler way is to use another character
instead of the slash.  A plus, for example:

	:s+one/two+one or two+

==============================================================================

*10.3*	Command ranges

The ":substitute" command, and many other : commands, can be applied to a
selection of lines.  This is called a range.
   The simple form of a range is {number},{number}.  For example:

	:1,5s/this/that/g

Executes the substitute command on the lines 1 to 5.  Line 5 is included.
The range is always placed before the command.

A single number can be used to address one specific line:

	:54s/President/Fool/

Some commands work on the whole file when you do not specify a range.  To make
them work on the current line the "." address is used.  The ":write" command
works like that.  Without a range, it writes the whole file.  To make it write
only the current line into a file:

	:.write otherfile

The first line always has number one.  How about the last line?  The "$"
character is used for this.  For example, to substitute in the lines from the
cursor to the end:

	:.,$s/yes/no/

The "%" range that we used before, is actually a short way to say "1,$", from
the first to the last line.


USING A PATTERN IN A RANGE

Suppose you are editing a chapter in a book, and want to replace all
occurrences of "grey" with "gray".  But only in this chapter, not in the next
one.  You know that only chapter boundaries have the word "Chapter" in the
first column.  This command will work then:

	:?^Chapter?,/^Chapter/s=grey=gray=g

You can see a search pattern is used twice.  The first "?^Chapter?" finds the
line above the current position that matches this pattern.  Thus the ?pattern?
range is used to search backwards.  Similarly, "/^Chapter/" is used to search
forward for the start of the next chapter.
   To avoid confusion with the slashes, the "=" character was used in the
substitute command here.  A slash or another character would have worked as
well.


ADD AND SUBTRACT

There is a slight error in the above command: If the title of the next chapter
had included "grey" it would be replaced as well.  Maybe that's what you
wanted, but what if you didn't?  Then you can specify an offset.
   To search for a pattern and then use the line above it:

	/Chapter/-1

You can use any number instead of the 1.  To address the second line below the
match:

	/Chapter/+2

The offsets can also be used with the other items in a range.  Look at this
one:

	:.+3,$-5

This specifies the range that starts three lines below the cursor and ends
five lines before the last line in the file.


USING MARKS

Instead of figuring out the line numbers of certain positions, remembering them
and typing them in a range, you can use marks.
   Place the marks as mentioned in chapter 3.  For example, use "mt" to mark
the top of an area and "mb" to mark the bottom.  Then you can use this range
to specify the lines between the marks (including the lines with the marks):

	:'t,'b


VISUAL MODE AND RANGES

You can select text with Visual mode.  If you then press ":" to start a colon
command, you will see this:

	:'<,'>

Now you can type the command and it will be applied to the range of lines that
was visually selected.

	Note:
	When using Visual mode to select part of a line, or using CTRL-V to
	select a block of text, the colon commands will still apply to whole
	lines.  This might change in a future version of Vim.

The '< and '> are actually marks, placed at the start and end of the Visual
selection.  The marks remain at their position until another Visual selection
is made.  Thus you can use the "'<" command to jump to position where the
Visual area started.  And you can mix the marks with other items:

	:'>,$

This addresses the lines from the end of the Visual area to the end of the
file.


A NUMBER OF LINES

When you know how many lines you want to change, you can type the number and
then ":".  For example, when you type "5:", you will get:

	:.,.+4

Now you can type the command you want to use.  It will use the range "."
(current line) until ".+4" (four lines down).  Thus it spans five lines.

==============================================================================

*10.4*	The global command

The ":global" command is one of the more powerful features of Vim.  It allows
you to find a match for a pattern and execute a command there.  The general
form is:

	:[range]global/{pattern}/{command}

This is similar to the ":substitute" command.  But, instead of replacing the
matched text with other text, the command {command} is executed.

	Note:
	The command executed for ":global" must be one that starts with a
	colon.  Normal mode commands can not be used directly.  The |:normal|
	command can do this for you.

Suppose you want to change "foobar" to "barfoo", but only in C++ style
comments.  These comments start with "//".  Use this command:

	:g+//+s/foobar/barfoo/g

This starts with ":g".  That is short for ":global", just like ":s" is short
for ":substitute".  Then the pattern, enclosed in plus characters.  Since the
pattern we are looking for contains a slash, this uses the plus character to
separate the pattern.  Next comes the substitute command that changes "foobar"
into "barfoo".
   The default range for the global command is the whole file.  Thus no range
was specified in this example.  This is different from ":substitute", which
works on one line without a range.
   The command isn't perfect, since it also matches lines where "//" appears
halfway a line, and the substitution will also take place before the "//".

Just like with ":substitute", any pattern can be used.  When you learn more
complicated patterns later, you can use them here.

==============================================================================

*10.5*	Visual block mode

With CTRL-V you can start selection of a rectangular area of text.  There are
a few commands that do something special with the text block.

There is something special about using the "$" command in Visual block mode.
When the last motion command used was "$", all lines in the Visual selection
will extend until the end of the line, also when the line with the cursor is
shorter.  This remains effective until you use a motion command that moves the
cursor horizontally.  Thus using "j" keeps it, "h" stops it.


INSERTING TEXT

The command  "I{string}<Esc>" inserts the text {string} in each line, just
left of the visual block.  You start by pressing CTRL-V to enter visual block
mode.  Now you move the cursor to define your block.  Next you type I to enter
Insert mode, followed by the text to insert.  As you type, the text appears on
the first line only.
   After you press <Esc> to end the insert, the text will magically be
inserted in the rest of the lines contained in the visual selection.  Example:

	include one 
	include two 
	include three 
	include four 

Move the cursor to the "o" of "one" and press CTRL-V.  Move it down with "