*25.2* Aligning text To center a range of lines, use the following command: > :{range}center [width] {range} is the usual command-line range. [width] is an optional line width to use for centering. If [width] is not specified, it defaults to the value of 'textwidth'. (If 'textwidth' is 0, the default is 80.) For example: > :1,5center 40 results in the following: I taught for a while. One ~ time, I was stopped by the ~ Fort Worth police, because my ~ homework was too hard. True ~ story. ~ RIGHT ALIGNMENT Similarly, the ":right" command right-justifies the text: :1,5right 30 gives this result: I taught for a while. One ~ time, I was stopped by the ~ Fort Worth police, because my ~ homework was too hard. True ~ story. ~ LEFT ALIGNMENT Finally there is this command: > :{range}left [margin] Unlike ":center" and ":right", however, the argument to ":left" is not the length of the line. Instead it is the left margin. If it is omitted, the text will be put against the left side of the screen (using a zero margin would do the same). If it is 5, the text will be indented 5 spaces. For example, use these commands: > :1left 5 :2,5left This results in the following: I taught for a while. One ~ time, I was stopped by the ~ Fort Worth police, because my ~ homework was too hard. True ~ story. ~ JUSTIFYING TEXT Vim has no built-in way of justifying text. However, there is a neat macro package that does the job. To use this package, execute the following command: > :runtime macros/justify.vim This Vim script file defines a new visual command "_j". To justify a block of text, highlight the text in Visual mode and then execute "_j". Look in the file for more explanations. To go there, do "gf" on this name: $VIMRUNTIME/macros/justify.vim. An alternative is to filter the text through an external program. Example: > :%!fmt
*25.3* Indents and tabs Indents can be used to make text stand out from the rest. The example texts in this manual, for example, are indented by eight spaces or a tab. You would normally enter this by typing a tab at the start of each line. Take this text: the first line ~ the second line ~ This is entered by typing a tab, some text, <Enter>, tab and more text. The 'autoindent' option inserts indents automatically: > :set autoindent When a new line is started it gets the same indent as the previous line. In the above example, the tab after the <Enter> is not needed anymore. INCREASING INDENT To increase the amount of indent in a line, use the ">" operator. Often this is used as ">>", which adds indent to the current line. The amount of indent added is specified with the 'shiftwidth' option. The default value is 8. To make ">>" insert four spaces wordth of indent, for example, type this: > :set shiftwidth=4 When used on the second line of the example text, this is what you get: the first line ~ the second line ~ "4>>" will increase the indent of four lines. TABSTOP If you want to make indents a multiple of 4, you set 'shiftwidth' to 4. But when pressing a Tab you still get 8 spaces worth of indent. To change this, set the 'softtabstop' option: > :set softtabstop=4 This will make the <Tab> key insert 4 spaces worth of indent. If there are already four spaces, a <Tab> character is used (saving seven characters in the file). (If you always want spaces and no tab characters, set the 'expandtab' option.) Note: You could set the 'tabstop' option to 4. However, if you edit the file another time, with 'tabstop' set to the default value of 8, it will look wrong. In other programs and when printing the indent will also be wrong. Therefore it is recommended to keep 'tabstop' at eight all the time. That's the standard value everywhere. CHANGING TABS You edit a file which was written with a tabstop of 3. In Vim it looks ugly, because it uses the normal tabstop value of 8. You can fix this by setting 'tabstop' to 3. But you have to do this every time you edit this file. Vim can change the use of tabstops in your file. First, set 'tabstop' to make the indents look good, then use the ":retab" command: > :set tabstop=3 :retab 8 The ":retab" command will change 'tabstop' to 8, while changing the text such that it looks the same. It changes spans of white space into tabs and spaces for this. You can now write the file. Next time you edit it the indents will be right without setting an option. Warning: When using ":retab" on a program, it may change white space inside a string constant. Therefore it's a good habit to use "\t" instead of a real tab
*25.4* Dealing with long lines Sometimes you will be editing a file that is wider than the number of columns in the window. When that occurs, Vim wraps the lines so that everything fits on the screen. If you switch the 'wrap' option off, each line in the file shows up as one line on the screen. Then the ends of the long lines disappear off the screen to the right. When you move the cursor to a character that can't be seen, Vim will scroll the text to show it. This is like moving a viewport over the text in the horizontal direction. By default, Vim does not display a horizontal scrollbar in the GUI. If you want to enable one, use the following command: > :set guioptions+=b One horizontal scrollbar will appear at the bottom of the Vim window. If you don't have a scrollbar or don't want to use it, use these commands to scroll the text. The cursor will stay in the same place, but it's move back into the visible text if necessary. zh scroll right 4zh scroll four characters right zH scroll half a window width right ze scroll right to put the cursor at the end zl scroll left 4zl scroll four characters left zL scroll half a window width left zs scroll left to put the cursor at the start Let's attempt to show this with one line of text. The cursor is on the "w" of "which". The "current window" above the line indicates the text that is currently visible. The "window"s below the text indicate the text that is visible after the command left of it. |<-- current window -->| some long text, part of which is visible in the window~ ze |<-- window -->| zH |<-- window -->| 4zh |<-- window -->| zh |<-- window -->| zl |<-- window -->| 4zl |<-- window -->| zL |<-- window -->| zs |<-- window -->| MOVING WITH WRAP OFF When 'wrap' is off and the text has scrolled horizontally, you can use the following commands to move the cursor to a character you can see. Thus text left and right of the window is ignored. These never cause the text to scroll: g0 to first visible character in this line g^ to first non-blank visible character in this line gm to middle of this line g$ to last visible character in this line |<-- window -->| some long text, part of which is visible ~ g0 g^ gm g$ BREAKING AT WORDS When preparing text for use by another program, you might have to make paragraphs without a line break. A disadvantage of using 'nowrap' is that you can't see the whole sentence you are working on. When 'wrap' is on, words are broken halfway, which makes them hard to read. A good solution for editing this kind of paragraph is setting the 'linebreak' option. Vim then breaks lines at an appropriate place when displaying the line. The text in the file remains unchanged. Without 'linebreak' text might look like this: +---------------------------------+ |letter generation program for a b| |ank. They wanted to send out a s| |pecial, personalized letter to th| |eir richest 1000 customers. Unfo| |rtunately for the programmer, he | +---------------------------------+ After: > :set linebreak it looks like this: +---------------------------------+ |letter generation program for a | |bank. They wanted to send out a | |special, personalized letter to | |their richest 1000 customers. | |Unfortunately for the programmer,| +---------------------------------+ Related options: 'breakat' specifies the characters where a break can be inserted. 'showbreak' specifies a string to show at the start of broken line. Set 'textwidth' to zero to avoid a paragraph to be split. MOVING BY VISIBLE LINES The "j" and "k" commands move to the next and previous lines. When used on a long line, this means moving a lot of screen lines at once. To move only one screen line, use the "gj" and "gk" commands. When a line doesn't wrap they do the same as "j" and "k". When the line does wrap, they move to a character displayed one line below or above. You might like to use these mappings, which bind these movement commands to the cursor keys: > :map <Up> gk :map <Down> gj TURNING A PARAGRAPH INTO ONE LINE If you want to import text into a program like MS-Word, each paragraph should be a single line. If your paragraphs are currently separated with empty lines, this is how you turn each paragraph into a single line: > :g/./,/^$/join That looks complicated. Let's break it up in pieces: :g/./ A ":global" command that finds all lines that contain at least one character. ,/^$/ A range, starting from the current line (the non-empty line) until an empty line. join The ":join" command joins the range of lines together into one line. Starting with this text, containing eight lines broken at column 30: +----------------------------------+ |A letter generation program | |for a bank. They wanted to | |send out a special, | |personalized letter. | | | |To their richest 1000 | |customers. Unfortunately for | |the programmer, | +----------------------------------+ You end up with two lines: +----------------------------------+ |A letter generation program for a | |bank. They wanted to send out a s| |pecial, personalized letter. | |To their richest 1000 customers. | |Unfortunately for the programmer, | +----------------------------------+ Note that this doesn't work when the separating line is blank but not empty; when it contains spaces and/or tabs. This command does work with blank lines: > :g/\S/,/^\s*$/join This still requires a blank or empty line at the end of the file for the last paragraph to be joined.
*25.5* Editing tables Suppose you are editing a table with four columns: nice table test 1 test 2 test 3 ~ input A 0.534 ~ input B 0.913 ~ You need to enter numbers in the third column. You could move to the second line, use "A", enter a lot of spaces and type the text. For this kind of editing there is a special option: > set virtualedit=all Now you can move the cursor to positions where there isn't any text. This is called "virtual space". Editing a table is a lot easier this way. Move the cursor by searching for the header of the last column: > /test 3 Now press "j" and you are right where you can enter the value for "input A". Typing "0.693" results in: nice table test 1 test 2 test 3 ~ input A 0.534 0.693 ~ input B 0.913 ~ Vim has automatically filled the gap in front of the new text for you. Now, to enter the next field in this column use "Bj". "B" moves back to the start of a white space separated word. Then "j" moves to the place where the next field can be entered. Note: You can move the cursor anywhere in the display, also beyond the end of a line. But Vim will not insert spaces there, until you insert a character in that position. COPYING A COLUMN You want to add a column, which should be a copy of the third column and placed before the "test 1" column. Do this in seven steps: 1. Move the cursor to the left upper corner of this column, e.g., with "/test 3". 2. Press CTRL-V to start blockwise Visual mode. 3. Move the cursor down two lines with "2j". You are now in "virtual space": the "input B" line of the "test 3" column. 4. Move the cursor right, to include the whole column in the selection, plus the space that you want between the columns. "9l" should do it. 5. Yank the selected rectangle with "y". 6. Move the cursor to "test 1", where the new column must be placed. 7. Press "P". The result should be: nice table test 3 test 1 test 2 test 3 ~ input A 0.693 0.534 0.693 ~ input B 0.913 ~ Notice that the whole "test 1" column was shifted right, also the line where the "test 3" column didn't have text. Go back to non-virtual cursor movements with: > :set virtualedit= VIRTUAL REPLACE MODE The disadvantage of using 'virtualedit' is that it "feels" different. You can't recognize tabs or spaces beyond the end of line when moving the cursor around. Another method can be used: Virtual replace mode. Suppose you have a line in a table that contains both tabs and other characters. Use "rx" on the first tab: inp 0.693 0.534 0.693 ~ | rx | V inpx0.693 0.534 0.693 ~ The layout is messed up. To avoid that, use the "gr" command: inp 0.693 0.534 0.693 ~ | grx | V inpx 0.693 0.534 0.693 ~ What happens is that the "gr" command makes sure the new character takes the right amount of screen space. Extra spaces or tabs are inserted to fill the gap. Thus what actually happens is that a tab is replaced by "x" and then blanks added to make the text after it keep it's place. In this case a tab is inserted. When you need to replace more than one character, you use the "R" command to go to replace mode (see |04.9|). This messes up the layout and replaces the wrong characters: inp 0 0.534 0.693 ~ | R0.786 | V inp 0.78634 0.693 ~ The "gR" command uses virtual replace mode. This preserves the layout: inp 0 0.534 0.693 ~ | gR0.786 | V inp 0.786 0.534 0.693 ~
*usr_26.txt* For Vim version 6.1. Last change: 2001 Sep 03 Repeating An editing task is hardly ever unstructured. A change often needs to be made several times. In this chapter a number of useful ways to repeat a change will be explained. |26.1| Repeating with Visual mode |26.2| Add and subtract |26.3| Making a change in many files |26.4| Using Vim from a shell script
*26.1* Repeating with Visual mode Visual mode is very handy for making a change in any sequence of lines. You can see the highlighted text, thus you can check if the correct lines are changed. But making the selection takes some typing. The "gv" command selects the same area again. This allows you to do another operation on the same text. Suppose you have some lines where you want to change "2001" to "2002" and "2000" to "2001": The financial results for 2001 are better ~ than for 2000. The income increased by 50%, ~ even though 2001 had more rain than 2000. ~ 2000 2001 ~ income 45,403 66,234 ~ First change "2001" to "2002". Select the lines in Visual mode, and use: > :s/2001/2002/g Now use "gv" to reselect the same text. It doesn't matter where the cursor is. Then use ":s/2000/2001/g" to make the second change. Obviously, you can repeat these changes several times.
*26.2* Add and subtract When repeating the change of one number into another, you often have a fixed offset. In the example above, one was added to each year. Instead of typing a substitute command for each year that appears, the CTRL-A command can be used. Using the same text as above, search for a year: > /19[0-9][0-9]\|20[0-9][0-9] Now press CTRL-A. The year will be increased by one: The financial results for 2002 are better ~ than for 2000. The income increased by 50%, ~ even though 2001 had more rain than 2000. ~ 2000 2001 ~ income 45,403 66,234 ~ Use "n" to find the next year, and press "." to repeat the CTRL-A ("." is a bit quicker to type). Repeat "n" and "." for all years that appear. Hint: set the 'hlsearch' option to see the matches you are going to change, then you can look ahead and do it faster. Adding more than one can be done by prepending the number to CTRL-A. Suppose you have this list: 1. item four ~ 2. item five ~ 3. item six ~ Move the cursor to "1." and type: > 3 CTRL-A The "1." will change to "4.". Again, you can use "." to repeat this on the other numbers. Another example: 006 foo bar ~ 007 foo bar ~ Using CTRL-A on these numbers results in: 007 foo bar ~ 010 foo bar ~ 7 plus one is 10? What happened here is that Vim recognized "007" as an octal number, because there is a leading zero. This notation is often used in C programs. If you do not want a number with leading zeros to be handled as octal, use this: > :set nrformats-=octal The CTRL-X command does subtraction in a similar way.
*26.3* Making a change in many files Suppose you have a variable called "x_cnt" and you want to change it to "x_counter". This variable is used in several of your C files. You need to change it in all files. This is how you do it. Put all the relevant files in the argument list: > :args *.c < This finds all C files and edits the first one. Now you can perform a substitution command on all these files: > :argdo %s/\<x_cnt\>/x_counter/ge | update The ":argdo" command takes an argument that is another command. That command will be executed on all files in the argument list. The "%s" substitute command that follows works on all lines. It finds the word "x_cnt" with "\<x_cnt\>". the "\<" and "\>" are used to match the whole word only, and not "px_cnt" or "x_cnt2". The flags for the substitute command include "g" to replace all occurences of "x_cnt" in the same line. The "e" flag is used to avoid an error message when "x_cnt" does not appear in the file. Otherwise ":argdo" would abort on the first file where "x_cnt" was not found. The "|" separates two commands. The following "update" command writes the file only if it was changed. If no "x_cnt" was changed to "x_counter" nothing happens. There is also the ":windo" command, which executes its argument in all windows. And ":bufdo" executes its argument on all buffers. Be careful with this, because you might have more files in the buffer list than you think. Check this with the ":buffers" command (or ":ls").
*26.4* Using Vim from a shell script Suppose you have a lot of files in which you need to change the string "-person-" to "Jones" and then print it. How do you do that? One way is to do a lot of typing. The other is to write a shell script to do the work. The Vim editor does a superb job as a screen-oriented editor when using Normal mode commands. For batch processing, however, Normal mode commands do not result in clear, commented command files; so here you will use Ex mode instead. This mode gives you a nice command-line interface that makes it easy to put into a batch file. ("Ex command" is just another name for a command-line (:) command.) The Ex mode commands you need are as follows: > %s/-person-/Jones/g write tempfile quit You put these commands in the file "change.vim". Now to run the editor in batch mode, use this shell script: > for file in *.txt; do vim -e -s $file < change.vim lpr -r tempfile done The for-done loop is a shell construct to repeat the two lines in between, while the $file variable is set to a different file name each time. The second line runs the Vim editor in Ex mode (-e argument) on the file $file and reads commands from the file "change.vim". The -s argument tells Vim to operate in silent mode. In other words, do not keep outputting the :prompt, or any other prompt for that matter. The "lpr -r tempfile" command prints the resulting "tempfile" and deletes it (that's what the -r argument does). READING FROM STDIN Vim can read text on standard input. Since the normal way is to read commands there, you must tell Vim to read text instead. This is done by passing the "-" argument in place of a file. Example: > ls | vim - This allows you to edit the output of the "ls" command, without first saving the text in a file. If you use the standard input to read text from, you can use the "-S" argument to read a script: > producer | vim -S change.vim - NORMAL MODE SCRIPTS If you really want to use Normal mode commands in a script, you can use it like this: > vim -s script file.txt ... < Note: "-s" has a different meaning when it is used without "-e". Here it means to source the "script" as Normal mode commands. When used with "-e" it means to be silent, and doesn't use the next argument as a file name. The commands in "script" are executed like you typed them. Don't forget that a line break is interpreted as pressing <Enter>. In Normal mode that moves the cursor to the next line. To create the script you can edit the script file and type the commands. You need to imagine what the result would be, which can be a bit difficult. Another way is to record the commands while you perform them manually. This is how you do that: > vim -w script file.txt ... All typed keys will be written to "script". If you make a small mistake you can just continue and remember to edit the script later. The "-w" argument appends to an existing script. That is good when you want to record the script bit by bit. If you want to start from scratch and start all over, use the "-W" argument. It overwrites any existing file.
*usr_27.txt* For Vim version 6.1. Last change: 2001 Sep 03 Search commands and patterns In chapter 3 a few simple search patterns were mentioned |03.9|. Vim can do much more complex searches. This chapter explains the most often used ones. A detailed specification can be found here: |pattern| |27.1| Ignoring case |27.2| Wrapping around the file end |27.3| Offsets |27.4| Matching multiple times |27.5| Alternatives |27.6| Character ranges |27.7| Character classes |27.8| Matching a line break |27.9| Examples
*27.1* Ignoring case By default, Vim's searches are case sensitive. Therefore, "include", "INCLUDE", and "Include" are three different words and a search will match only one of them. Now switch on the 'ignorecase' option: > :set ignorecase Search for "include" again, and now it will match "Include", "INCLUDE" and "InClUDe". (set the 'hlsearch' option to quickly see where a pattern matches.) You can switch this off again with: > :set noignorecase But lets keep it set, and search for "INCLUDE". It will match exactly the same text as "include" did. Now set the 'smartcase' option: > :set ignorecase smartcase If you have a pattern with at least one uppercase character, the search becomes case sensitive. The idea is that you didn't have to type that uppercase character, so you must have done it because you wanted case to match. That's smart! With these two options set you find the following matches: pattern matches ~ word word, Word, WORD, WoRd, etc. Word Word WORD WORD WoRd WoRd CASE IN ONE PATTERN If you want to ignore case for one specific pattern, you can do this by prepending the "\c" string. Using "\C" will make the pattern to match case. This overrules the 'ignorecase' and 'smartcase' options, when "\c" or "\C" is used their value doesn't matter. pattern matches ~ \Cword word \CWord Word \cword word, Word, WORD, WoRd, etc. \cWord word, Word, WORD, WoRd, etc. A big advantage of using "\c" and "\C" is that it sticks with the pattern. Thus if you repeat a pattern from the search history, the same will happen, no matter if 'ignorecase' or 'smartcase' was changed. Note: The use of "\" items in search patterns depends on the 'magic' option. In this chapters we will assume 'magic' is on, because that is the standard and recommended setting. If you would change it, many search patterns would suddenly become invalid. Note: If your search takes much longer than you expected, you can interrupt it with CTRL-C on Unix and CTRL-Break on MS-DOS and MS-Windows.
*27.2* Wrapping around the file end By default, a forward search starts searching for the given string at the current cursor location. It then proceeds to the end of the file. If it has not found the string by that time, it starts from the beginning and searches from the start of the file to the cursor location. Keep in mind that when repeating the "n" command to search for the next match, you eventually get back to the first match. If you don't notice this you keep searching forever! To give you a hint, Vim displays this message: search hit BOTTOM, continuing at TOP ~ If you use the "?" command, to search in the other direction, you get this message: search hit TOP, continuing at BOTTOM ~ Still, you don't know when you are back at the first match. One way to see this is by switching on the 'ruler' option: > :set ruler Vim will display the cursor position in the lower righthand corner of the window (in the status line if there is one). It looks like this: 101,29 84% ~ The first number is the line number of the cursor. Remember the line number where you started, so that you can check if you passed this position again. NOT WRAPPING To turn off search wrapping, use the following command: > :set nowrapscan Now when the search hits the end of the file, an error message displays: E385: search hit BOTTOM without match for: forever ~ Thus you can find all matches by going to the start of the file with "gg" and keep searching until you see this message. If you search in the other direction, using "?", you get: E384: search hit TOP without match for: forever ~
*27.3* Offsets By default, the search command leaves the cursor positioned on the beginning of the pattern. You can tell Vim to leave it some other place by specifying an offset. For the forward search command "/", the offset is specified by appending a slash (/) and the offset: > /default/2 This command searches for the pattern "default" and then moves to the beginning of the second line past the pattern. Using this command on the paragraph above, Vim finds the word "default" in the first line. Then the cursor is moved two lines down and lands on "an offset". If the offset is a simple number, the cursor will be placed at the beginning of the line that many lines from the match. The offset number can be positive or negative. If it is positive, the cursor moves down that many lines; if negative, it moves up. CHARACTER OFFSETS The "e" offset indicates an offset from the end of the match. It moves the cursor onto the last character of the match. The command: > /const/e puts the cursor on the t of "const". From that position, adding a number moves forward that many characters. This command moves to the character just after the match: > /const/e+1 A positive number moves the cursor to the right, a negative number moves it to the left. For example: > /const/e-1 moves the cursor to the "s" of "const". If the offset begins with "b", the cursor moves to the beginning of the pattern. That's not very useful, since leaving out the "b" does the same thing. It does get useful when a number is added or subtracted. The cursor then goes forward or backward that many characters. For example: > /const/b+2 Moves the cursor to the beginning of the match and then two characters to the right. Thus it lands on the "n". REPEATING To repeat searching for the previously used search pattern, but with a different offset, leave out the pattern: > /that //e Is equal to: > /that/e To repeat with the same offset: > / "n" does the same thing. To remove a previously used offset: > // SEARCHING BACKWARDS The "?" command uses offsets in the same way, but you must use "?" to separate the offset from the pattern, instead of "/": > ?const?e-2 The "b" and "e" keep their meaning, they don't change direction with the use of "?". START POSITION When starting a search, it normally starts at the cursor position. When you specify a line offset, this can cause trouble. For example: > /const/-2 This finds the next word "const" and then moves two lines up. If you use "n" to search again, Vim could start at the current position and find the same "const" match. Then using the offset again, you would be back where you started. You would be stuck! It could be worse: Suppose there is another match with "const" in the next line. Then repeating the forward search would find this match and move two lines up. Thus you would actually move the cursor back! When you specify a character offset, Vim will compensate for this. Thus the search starts a few characters forward or backward, so that the same match isn't found again.
*27.4* Matching multiple times The "*" item specifies that the item before it can match any number of times. Thus: > /a* matches "a", "aa", "aaa", etc. But also "" (the empty string), because zero times is included. The "*" only applies to the item directly before it. Thus "ab*" matches "a", "ab", "abb", "abbb", etc. To match a whole string multiple times, it must be grouped into one item. This is done by putting "\(" before it and "\)" after it. Thus this command: > /\(ab\)* Matches: "ab", "abab", "ababab", etc. And also "". To avoid matching the empty string, use "\+". This makes the previous item match one or more times. > /ab\+ Matches "ab", "abb", "abbb", etc. It does not match "a" when no "b" follows. To match an optional item, use "\=". Example: > /folders\= Matches "folder" and "folders". SPECIFIC COUNTS To match a specific number of items use the form "\{n,m}". "n" and "m" are numbers. The item before it will be matched "n" to "m" times (inclusive). Example: > /ab\{3,5} matches "abbb", "abbbb" and "abbbbb". When "n" is omitted, it defaults to zero. When "m" is omitted it defaults to infinity. When ",m" is omitted, it matches exactly "n" times. Examples: pattern match count ~ \{,4} 0, 1, 2, 3 or 4 \{3,} 3, 4, 5, etc. \{0,1} 0 or 1, same as \= \{0,} 0 or more, same as * \{1,} 1 or more, same as \+ \{3} 3 MATCHING AS LITTLE AS POSSIBLE The items so far match as many characters as they can find. To match as few as possible, use "\{-n,m}". It works the same as "\{n,m}", except that the minimal amount possible is used. For example, use: > /ab\{-1,3} Will match "ab" in "abbb". Actually, it will never match more than one b, because there is no reason to match more. It requires something else to force it to match more than the lower limit. The same rules apply to removing "n" and "m". It's even possible to remove both of the, resulting in "\{-}". This matches the item before it zero or more times, as few as possible. The item by itself always match zero times. It is useful when combined with something else. Example: > /a.\{-}b This matches "axb" in "axbxb". If this pattern would be used: > /a.*b It would try to match as many characters as possible with ".*", thus it matches "axbxb" as a whole.
*27.5* Alternatives The "or" operator in a pattern is "\|". Example: > /foo\|bar This matches "foo" or "bar". More alternatives can be concatenated: > /one\|two\|three Matches "one", "two" and "three". To match multiple times, the whole thing must be placed in "\(" and "\)": > /\(foo\|bar\)\+ This matches "foo", "foobar", "foofoo", "barfoobar", etc. Another example: > /end\(if\|while\|for\) This matches "endif", "endwhile" and "endfor". A related item is "\&". This requires that both alternatives match in the same place. The resulting match uses the last alternative. Example: > /forever\&... This matches "for" in "forever". It will not match "fortuin", for example.
*27.6* Character ranges To match "a", "b" or "c" you could use "/a\|b\|c". When you want to match all letters from "a" to "z" this gets very long. There is a shorter method: > /[a-z] The [] construct matches a single character. Inside you specify which characters to match. You can include a list of characters, like this: > /[0123456789abcdef] This will match any of the characters included. For consecutive characters you can specify the range. "0-3" stands for "0123". "w-z" stands for "wxyz". Thus the same command as above can be shortened to: > /[0-9a-f] To match the "-" character itself make it the first or last one in the range. These special characters are accepted to make it easier to use them inside a [] range (they can actually be used anywhere in the search pattern): \e <Esc> \t <Tab> \r <CR> \b <BS> There are a few more special cases for [] ranges, see |/[]| for the whole story. COMPLIMENTED RANGE To avoid matching a specific character, use "^" at the start of the range. The [] item then matches everything but the characters included. Example: > /"[^"]*" < " a double quote [^"] any character that is not a double quote * as many as possible " a double quote again This matches "foo" and "3!x", including the double quotes. PREDEFINED RANGES A number of ranges are used very often. Vim provides a shortcut for these. For example: > /\a Finds alphabetic characters. This is equal to using "/[a-zA-Z]". Here are a few more of these: item matches equivalent ~ \d digit [0-9] \D non-digit [^0-9] \x hex digit [0-9a-fA-F] \X non-hex digit [^0-9a-fA-F] \s white space [ ] (<Tab> and <Space>) \S non-white characters [^ ] (not <Tab> and <Space>) \l lowercase alpha [a-z] \L non-lowercase alpha [^a-z] \u uppercase alpha [A-Z] \U non-uppercase alpha [^A-Z] Note: Using these predefined ranges works a lot faster than the character range it stands for. These items can not be used inside []. Thus "[\d\l]" does NOT work to match a digit or lowercase alpha. Use "\(\d\|\l\)" instead. See |/\s| for the whole list of these ranges.
*27.7* Character classes The character range matches a fixed set of characters. A character class is similar, but with an essential difference: The set of characters can be redefined without changing the search pattern. For example, search for this pattern: > /\f\+ The "\f" items stands for file name characters. Thus this matches a sequence of characters that can be a file name. Which characters can be part of a file name depends on the system you are using. On MS-Windows, the backslash is included, on Unix it is not. This is specified with the 'isfname' option. The default value for Unix is: > :set isfname isfname=@,48-57,/,.,-,_,+,,,#,$,%,~,= For other systems the default value is different. Thus you can make a search pattern with "\f" to match a file name, and it will automatically adjust to the system you are using it on. Note: Actually, Unix allows using just about any character in a file name, including white space. Including these characters in 'isfname' would be theoretically correct. But it would make it impossible to find the end of a file name in text. Thus the default value of 'isfname' is a compromise. The character classes are: item matches option ~ \i identifier characters 'isident' \I like \i, excluding digits \k keyword characters 'iskeyword' \K like \k, excluding digits \p printable characters 'isprint' \P like \p, excluding digits \f file name characters 'isfname' \F like \f, excluding digits
*27.8* Matching a line break Vim can find a pattern that includes a line break. You need to specify where the line break happens, because all items mentioned so far don't match a line break. To check for a line break in a specific place, use the "\n" item: > /the\nword This will match at a line that ends in "the" and the next line starts with "word". To match "the word" as well, you need to match a space or a line break. The item to use for it is "\_s": > /the\_sword To allow any amount of white space: > /the\_s\+word This also matches when "the " is at the end of a line and " word" at the start of the next one. "\s" matches white space, "\_s" matches white space or a line break. Similarly, "\a" matches an alphabetic character, and "\_a" matches an alphabetic character or a line break. The other character classes and ranges can be modified in the same way by inserting a "_". Many other items can be made to match a line break by prepending "\_". For example: "\_." matches any character or a line break. Note: "\_.*" matches everything until the end of the file. Be careful with this, it can make a search command very slow. Another example is "\_[]", a character range that includes a line break: > /"\_[^"]*" This finds a text in double quotes that may be split up in several lines.
*27.9* Examples Here are a few search patterns you might find useful. This shows how the items mentioned above can be combined. FINDING A CALIFORNIA LICENSE PLATE A sample license place number is "1MGU103". It has one digit, three uppercase letters and three digits. Directly putting this into a search pattern: > /\d\u\u\u\d\d\d Another way is to specify that there are three digits and letters with a count: > /\d\u\{3}\d\{3} Using [] ranges instead: > /[0-9][A-Z]\{3}[0-9]\{3} Which one of these you should use? Whichever one you can remember. The simple way you can remember is much faster than the fancy way that you can't. If you can remember them all, then avoid the last one, because it's both more typing and slower to execute. FINDING AN IDENTIFIER In C programs (and many other computer languages) an identifier starts with a letter and further consists of letters and digits. Underscores can be used too. This can be found with: > /\<\h\w*\> "\<" and "\>" are used to find only whole words. "\h" stands for "[A-Za-z_]" and "\w" for [0-9A-Za-z_]". Note: "\<" and "\>" depend on the 'iskeyword' option. If it includes "-", for example, then "ident-" is not matched. In this situation use: > /\w\@<!\h\w*\w\@! < This checks if "\w" does not match before or after the identifier. See |/\@<!| and |/\@!|.
*usr_28.txt* For Vim version 6.1. Last change: 2001 Oct 21 Folding Structured text can be separated in sections. And sections in sub-sections. Folding allows you to display a section as one line, providing an overview. This chapter explains the different ways this can be done. |28.1| What is folding? |28.2| Manual folding |28.3| Working with folds |28.4| Saving and restoring folds |28.5| Folding by indent |28.6| Folding with markers |28.7| Folding by syntax |28.8| Folding by expression |28.9| Folding unchanged lines |28.10| Which fold method to use?
*28.1* What is folding? Folding is used to show a range of lines in the buffer as a single line on the screen. Like a piece of paper which is folded to make it shorter: +------------------------+ | line 1 | | line 2 | | line 3 | |_______________________ | \ \ \________________________\ / folded lines / /________________________/ | line 12 | | line 13 | | line 14 | +------------------------+ The text is still in the buffer, unchanged. Only the way lines are displayed is affected by folding. The advantage of folding is that you can get a better overview of the structure of text, by folding lines of a section and replacing it with a line that indicates that there is a section.
*28.2* Manual folding Try it out: Position the cursor in a paragraph and type: > zfap You will see that the paragraph is replaced by a highlighted line. You have created a fold. |zf| is an operator and |ap| a text object selection. You can use the |zf| operator with any movement command to create a fold for the text that it moved over. |zf| also works in Visual mode. To view the text again, open the fold by typing: > zo And you can close the fold again with: > zc All the folding commands start with 'z'.  The letter after the "z" has a mnemonic meaning to make it easier to remember the commands: zf F-old creation zo O-pen a fold zc C-lose a fold Folds can be nested: A region of text that contains folds can be folded again. For example, you can fold each paragraph in this section, and then fold all the sections in this chapter. Try it out. You will notice that opening the fold for the whole chapter will restore the nested folds as they were, some may be open and some may be closed. Suppose you have created several folds, and now want to view all the text. You could go to each fold and type "zo". To do this faster, use this command: > zr This will R-educe the folding. The opposite is: > zm This folds M-ore. You can repeat "zr" and "zm" to open and close nested folds of several levels. If you have nested several levels deep, you can open all of them with: > zR This R-educes folds until there are none left. And you can close all folds with: > zM This folds M-ore and M-ore. You can quickly disable the folding with the |zn| command. Then |zN| brings back the folding as it was. |zi| toggles between the two. This is a useful way of working: - create folds to get overview on your file - move around to where you want to do your work - do |zi| to look at the text and edit it - do |zi| again to go back to moving around More about manual folding in the reference manual: |fold-manual|
*28.3* Working with folds When some folds are closed, movement commands like "j" and "k" move over a fold like it was a single, empty line. This allows you to quickly move around over folded text. You can yank, delete and put folds as if it was a single line. This is very useful if you want to reorder functions in a program. First make sure that each fold contains a whole function (or a bit less) by selecting the right 'foldmethod'. Then delete the function with "dd", move the cursor and put it with "p". If some lines of the function are above or below the fold, you can use Visual selection: - put the cursor on the first line to be moved - hit "V" to start Visual mode - put the cursor on the last line to be moved - hit "d" to delete the selected lines. - move the cursor to the new position and "p"ut the lines there. It is sometimes difficult to see or remember where a fold is located, thus where a |zo| command would actually work. To see the defined folds: > :set foldcolumn=4 This will show a small column on the left of the window to indicate folds. A "+" is shown for a closed fold. A "-" is shown at the start of each open fold and "|" at following lines of the fold. You can use the mouse to open a fold by clicking on the "+" in the foldcolumn. Clicking on the "-" or a "|" below it will close an open fold. To open all folds at the cursor line use |zO|. To close all folds at the cursor line use |zC|. To delete a fold at the cursor line use |zd|. To delete all folds at the cursor line use |zD|. When in Insert mode, the fold at the cursor line is never closed. That allows you to see what you type! Folds are opened automatically when jumping around or moving the cursor left or right. For example, the "0" command opens the fold under the cursor (if 'foldopen' contains "hor", which is the default). The 'foldopen' option can be changed to open folds for specific commands. If you want the line under the cursor always to be open, do this: > :set foldopen=all Warning: You won't be able to move onto a closed fold then. You might want to use this only temporarily and then set it back to the default: > :set foldopen& You can make folds close automatically when you move out of it: > :set foldclose=all This will re-apply 'foldlevel' to all folds that don't contain the cursor. You have to try it out if you like how this feels. Use |zm| to fold more and |zr| to fold less (reduce folds). The folding is local to the window. This allows you to open two windows on the same buffer, one with folds and one without folds. Or one with all folds closed and one with all folds open.
*28.4* Saving and restoring folds When you abandon a file (starting to edit another one), the state of the folds is lost. If you come back to the same file later, all manually opened and closed folds are back to their default. When folds have been created manually, all folds are gone! To save the folds use the |:mkview| command: > :mkview This will store the settings and other things that influence the view on the file. You can change what is stored with the 'viewoptions' option. When you come back to the same file later, you can load the view again: > :loadview You can store up to ten views on one file. For example, to save the current setup as the third view and load the second view: > :mkview 3 :loadview 2 Note that when you insert or delete lines the views might become invalid. Also check out the 'viewdir' option, which specifies where the views are stored. You might want to delete old views now and then.
*28.5* Folding by indent Defining folds with |zf| is a lot of work. If your text is structured by giving lower level items a larger indent, you can use the indent folding method. This will create folds for every sequence of lines with the same indent. Lines with a larger indent will become nested folds. This works well with many programming languages. Try this by setting the 'foldmethod' option: > :set foldmethod=indent Then you can use the |zm| and |zr| commands to fold more and reduce folding. It's easy to see on this example text: This line is not indented This line is indented once This line is indented twice This line is indented once This line is not indented This line is indented once This line is indented once Note that the relation between the amount of indent and the fold depth depends on the 'shiftwidth' option. Each 'shiftwidth' worth of indent adds one to the depth of the fold. This is called a fold level. When you use the |zr| and |zm| commands you actually increase or decrease the 'foldlevel' option. You could also set it directly: > :set foldlevel=3 This means that all folds with three times a 'shiftwidth' indent or more will be closed. The lower the foldlevel, the more folds will be closed. When 'foldlevel' is zero, all folds are closed. |zM| does set 'foldlevel' to zero. The opposite command |zR| sets 'foldlevel' to the deepest fold level that is present in the file. Thus there are two ways to open and close the folds: (A) By setting the fold level. This gives a very quick way of "zooming out" to view the structure of the text, move the cursor, and "zoom in" on the text again. (B) By using |zo| and |zc| commands to open or close specific folds. This allows opening only those folds that you want to be open, while other folds remain closed. This can be combined: You can first close most folds by using |zm| a few times and then open a specific fold with |zo|. Or open all folds with |zR| and then close specific folds with |zc|. But you cannot manually define folds when 'foldmethod' is "indent", as that would conflict with the relation between the indent and the fold level. More about folding by indent in the reference manual: |fold-indent|
*28.6* Folding with markers Markers in the text are used to specify the start and end of a fold region. This gives precise control over which lines are included in a fold. The disadvantage is that the text needs to be modified. Try it: > :set foldmethod=marker Example text, as it could appear in a C program: /* foobar () {{{ */ int foobar() { /* return a value {{{ */ return 42; /* }}} */ } /* }}} */ Notice that the folded line will display the text before the marker. This is very useful to tell what the fold contains. It's quite annoying when the markers don't pair up correctly after moving some lines around. This can be avoided by using numbered markers. Example: /* global variables {{{1 */ int varA, varB; /* functions {{{1 */ /* funcA() {{{2 */ void funcA() {} /* funcB() {{{2 */ void funcB() {} /* }}}1 */ At every numbered marker a fold at the specified level begins. This will make any fold at a higher level stop here. You can just use numbered start markers to define all folds. Only when you want to explicitly stop a fold before another starts you need to add an end marker. More about folding with markers in the reference manual: |fold-marker|
*28.7* Folding by syntax For each language Vim uses a different syntax file. This defines the colors for various items in the file. If you are reading this in Vim, in a terminal that supports colors, the colors you see are made with the "help" syntax file. In the syntax files it is possible to add syntax items that have the "fold" argument. These define a fold region. This requires writing a syntax file and adding these items in it. That's not so easy to do. But once it's done, all folding happens automatically. Here we'll assume you are using an existing syntax file. Then there is nothing more to explain. You can open and close folds as explained above. The folds will be created and deleted automatically when you edit the file. More about folding by syntax in the reference manual: |fold-syntax|
*28.8* Folding by expression This is similar to folding by indent, but instead of using the indent of a line a user function is called to compute the fold level of a line. You can use this for text where something in the text indicates which lines belong together. An example is an e-mail message where the quoted text is indicated by a ">" before the line. To fold these quotes use this: > :set foldmethod=expr :set foldexpr=strlen(substitute(substitute(getline(v:lnum),'\\s','',\"g\"),'[^>].*','','')) You can try it out on this text: > quoted text he wrote > quoted text he wrote > > double quoted text I wrote > > double quoted text I wrote Explanation for the 'foldexpr' used in the example (inside out): getline(v:lnum) gets the current line substitute(...,'\\s','','g') removes all white space from the line substitute(...,'[^>].*','','')) removes everything after leading '>'s strlen(...) counts the length of the string, which is the number of '>'s found Note that a backslash must be inserted before every space, double quote and backslash for the ":set" command. If this confuses you, do > :set foldexpr to check the actual resulting value. To correct a complicated expression, use the command-line completion: > :set foldexpr=<Tab> Where <Tab> is a real Tab. Vim will fill in the previous value, which you can then edit. More about folding by expression in the reference manual: |fold-expr|
*28.9* Folding unchanged lines This is useful when you set the 'diff' option in the same window. The |vimdiff| command does this for you. Example: > setlocal diff foldmethod=diff scrollbind nowrap foldlevel=1 Do this in every window that shows a different version of the same file. You will clearly see the differences between the files, while the text that didn't change is folded. For more details see |fold-diff|.
*28.10* Which fold method to use? All these possibilities makes you wonder which method you should chose. Unfortunately, there is no golden rule. Here are some hints. If there is a syntax file with folding for the language you are editing, that is probably the best choice. If there isn't one, you might try to write it. This requires a good knowledge of search patterns. It's not easy, but when it's working you will not have to define folds manually. Typing commands to manually fold regions can be used for unstructured text. Then use the |:mkview| command to save and restore your folds. The marker method requires you to change the file. If you are sharing the files with other people or you have to meet company standards, you might not be allowed to add them. The main advantage of markers is that you can put them exactly where you want them. That avoids that a few lines are missed when you cut and paste folds. And you can add a comment about what is contained in the fold. Folding by indent is something that works in many files, but not always very well. Use it when you can't use one of the other methods. However, it is very useful for outlining. Then you specifically use one 'shiftwidth' for each nesting level. Folding with expressions can make folds in almost any structured text. It is quite simple to specify, especially if the start and end of a fold can easily be recognized. If you use the "expr" method to define folds, but they are not exactly how you want them, you could switch to the "manual" method. This will not remove the defined folds. Then you can delete or add folds manually.
*usr_29.txt* For Vim version 6.1. Last change: 2001 Sep 09 Moving through programs The creator of Vim is a computer programmer. It's no surprise that Vim contains many features to aid in writing programs. Jump around to find where identifiers are defined and used. Preview declarations in a separate window. There is more in the next chapter. |29.1| Using tags |29.2| The preview window |29.3| Moving through a program |29.4| Finding global identifiers |29.5| Finding local identifiers
*29.1* Using tags What is a tag? It is a location where an identifier is defined. An example is a function definition in a C or C++ program. A list of tags is kept in a tags file. This can be used by Vim to directly jump from any place to the tag, the place where an identifier is defined. To generate the tags file for all C files in the current directory, use the following command: > ctags *.c "ctags" is a separate program. Most Unix systems already have it installed. If you do not have it yet, you can find Exuberant ctags here: http://ctags.sf.net ~ Now when you are in Vim and you want to go to a function definition, you can jump to it by using the following command: > :tag startlist This command will find the function "startlist" even if it is in another file. The CTRL-] command jumps to the tag of the word that is under the cursor. This makes it easy to explore a tangle of C code. Suppose, for example, that you are in the function "write_block". You can see that it calls "write_line". But what does "write_line" do? By placing the cursor on the call to "write_line" and pressing CTRL-], you jump to the definition of this function. The "write_line" function calls "write_char". You need to figure out what it does. So you position the cursor over the call to "write_char" and press CTRL-]. Now you are at the definition of "write_char". +-------------------------------------+ |void write_block(char **s; int cnt) | |{ | | int i; | | for (i = 0; i < cnt; ++i) | | write_line(s[i); | |} | | +-----------|-------------------------+ | CTRL-] | | +----------------------------+ +--> |void write_line(char *s) | |{ | | while (*s != 0) | | write_char(*s++); | |} | | +--------|-------------------+ | CTRL-] | | +------------------------------------+ +--> |void write_char(char c) | |{ | | putchar((int)(unsigned char)c); | |} | +------------------------------------+ The ":tags" command shows the list of tags that you traversed through: :tags # TO tag FROM line in file/text ~ 1 1 write_line 8 write_block.c ~ 2 1 write_char 7 write_line.c ~ > ~ > Now to go back. The CTRL-T command goes to the preceding tag. In the example above you get back to the "write_line" function, in the call to 'write_char". This command takes a count argument that indicates how many tags to jump back. You have gone forward, and now back. Let's go forward again. The following command goes to the tag on top of the list: > :tag You can prefix it with a count and jump forward that many tags. For example: ":3tag". CTRL-T also can be preceded with a count. These commands thus allow you to go down a call tree with CTRL-] and back up again with CTRL-T. Use ":tags" to find out where you are. SPLIT WINDOWS The ":tag" command replaces the file in the current window with the one containing the new function. But suppose you want to see not only the old function but also the new one? You can split the window using the ":split" command followed by the ":tag" command. Vim has a shorthand command that does both: > :stag tagname To split the current window and jump to the tag under the cursor use this command: > CTRL-W ] If a count is specified, the new window will be that many lines high. MORE TAGS FILES When you have files in many directories, you can create a tags file in each of them. Vim will then only be able to jump to tags within that directory. To find more tags files, set the 'tags' option to include all the relevant tags files. Example: > :set tags=./tags,./../tags,./*/tags This finds a tags file in the same directory as the current file, one directory level higher and in all subdirectories. This is quite a number of tags files, but it may still not be enough. For example, when editing a file in "~/proj/src", you will not find the tags file "~/proj/sub/tags". For this situation Vim offers to search a whole directory tree for tags files. Example: > :set tags=~/proj/**/tags ONE TAGS FILE When Vim has to search many places for tags files, you can hear the disk rattling. It may get a bit slow. In that case it's better to spend this time while generating one big tags file. You might do this overnight. This requires the Exuberant ctags program, mentioned above. It offers an argument to search a whole directory tree: > cd ~/proj ctags -R . The nice thing about this is that Exuberant ctags recognizes various file types. Thus this doesn't work just for C and C++ programs, also for Eiffel and even Vim scripts. See the ctags documentation to tune this. Now you only need to tell Vim where your big tags file is: > :set tags=~/proj/tags MULTIPLE MATCHES When a function is defined multiple times (or a method in several classes), the ":tag" command will jump to the first one. If there is a match in the current file, that one is used first. You can now jump to other matches for the same tag with: > :tnext Repeat this to find further matches. If there are many, you can select which one to jump to: > :tselect tagname Vim will present you with a list of choices: # pri kind tag file ~ 1 F f mch_init os_amiga.c ~ mch_init() ~ 2 F f mch_init os_mac.c ~ mch_init() ~ 3 F f mch_init os_msdos.c ~ mch_init(void) ~ 4 F f mch_init os_riscos.c ~ mch_init() ~ Enter nr of choice (<CR> to abort): ~ You can now enter the number (in the first column) of the match that you would like to jump to. The information in the other columns give you a good idea of where the match is defined. To move between the matching tags, these commands can be used: :tfirst go to first match :[count]tprevious go to [count] previous match :[count]tnext go to [count] next match :tlast go to last match If [count] is omitted then one is used. GUESSING TAG NAMES Command line completion is a good way to avoid typing a long tag name. Just type the first bit and press <Tab>: > :tag write_<Tab> You will get the first match. If it's not the one you want, press <Tab> until you find the right one. Sometimes you only know part of the name of a function. Or you have many tags that start with the same string, but end differently. Then you can tell Vim to use a pattern to find the tag. Suppose you want to jump to a tag that contains "block". First type this: > :tag /block Now use command line completion: press <Tab>. Vim will find all tags that contain "block" and use the first match. The "/" before a tag name tells Vim that what follows is not a literal tag name, but a pattern. You can use all the items for search patterns here. For example, suppose you want to select a tag that starts with "write_": > :tselect /^write_ The "^" specifies that the tag starts with "write". Otherwise it would also be found halfway a tag name. Similarly "$" at the end makes sure the pattern matches until the end of a tag. A TAGS BROWSER Since CTRL-] takes you to the definition of the identifier under the cursor, you can use a list of identifier names as a table of contents. Here is an example. First create a list of identifiers (this requires Exuberant ctags): > ctags --c-types=f -f functions *.c Now start Vim without a file, and edit this file in Vim, in a vertically split window: > vim :vsplit functions The window contains a list of all the functions. There is some more stuff, but you can ignore that. Do ":set ts=99" to clean it up a bit. In this window, define a mapping: > :nmap <buffer> <CR> 0ye<C-W>w:tag <C-R>"<CR> Move the cursor to the line that contains the function you want to go to. Now press <Enter>. Vim will go to the other window and jump to the selected function. RELATED ITEMS You can set 'ignorecase' to make case in tag names be ignored. The 'tagbsearch' option tells if the tags file is sorted or not. The default is to assume a sorted tags file, which makes a tags search a lot faster, but doesn't work if the tags file isn't sorted. The 'taglength' option can be used to tell Vim the number of significant characters in a tag. When you use the SNiFF+ program, you can use the Vim interfact to it |sniff|. SNiFF+ is a commercial program. Cscope is a free program. I does not only find places where an identifier is declared, but also where it is used. See |cscope|.
*29.2* The preview window When you edit code that contains a function call, you need to use the correct arguments. To know what values to pass you can look at how the function is defined. The tags mechanism works very well for this. Preferably the definition is displayed in another window. For this the preview window can be used. To open a preview window to display the function "write_char": > :ptag write_char Vim will open a window, and jumps to the tag "write_char". Then it takes you back to the original position. Thus you can continue typing without the need to use a CTRL-W command. If the name of a function appears in the text, you can get its definition in the preview window with: > CTRL-W } There is a script that automatically displays the text where the word under the cursor was defined. See |CursorHold-example| To close the preview window again, use this command: > :pclose To edit a specific file in the preview window, use ":pedit". This can be useful to edit a header file, for example: > :pedit defs.h Finally, ":psearch" can be used to find a word in the current file and any included files and display the match in the preview window. This is especially useful when using library functions, for which you do not have a tags file. Example: > :psearch popen This will show the "stdio.h" file in the preview window, with the function prototype for popen(): FILE *popen __P((const char *, const char *)); ~ You can specify the height of the preview window, when it is opened, with the 'previewheight' option.
*29.3* Moving through a program Since a program is structured, Vim can recognize items in it. Specific commands can be used to move around. C programs often contain constructs like this: #ifdef USE_POPEN ~ fd = popen("ls", "r") ~ #else ~ fd = fopen("tmp", "w") ~ #endif ~ But then much longer, and possibly nested. Position the cursor on the "#ifdef" and press %. Vim will jump to the "#else". Pressing % again takes you to the "#endif". Another % takes you to the "#ifdef" again. When the construct is nested, Vim will find the matching items. This is a good way to check if you didn't forget an "#endif". When you are somewhere inside a "#if" - "#endif", you can jump to the start of it with: > [# If you are not after a "#if" or "#ifdef" Vim will beep. To jump forward to the next "#else" or "#endif" use: > ]# These two commands skip any "#if" - "#endif" blocks that it encounters. Example: #if defined(HAS_INC_H) ~ a = a + inc(); ~ # ifdef USE_THEME ~ a += 3; ~ # endif ~ set_width(a); ~ With the cursor in the last line, "[#" moves to the first line. The "#ifdef" - "#endif" block in the middle is skipped. MOVING IN CODE BLOCKS In C code blocks are enclosed in {}. These can get pretty long. To move to the start of the outer block use the "[[" command. Use "]]" to find the end. This assumes that the "{" and "}" are in the first column. The "[{" command moves to the start of the current block. It skips over pairs of {} at the same level. "]}" jumps to the end. An overview: function(int a) +-> { | if (a) | +-> { [[ | | for (;;) --+ | | +-> { | | [{ | | foo(32); | --+ | | [{ | if (bar(a)) --+ | ]} | +-- | +-- break; | ]} | | | } <-+ | | ]] +-- foobar(a) | | } <-+ | } <-+ When writing C++ or Java, the outer {} block is for the class. The next level of {} is for a method. When somewhere inside a class use "[m" to find the previous start of a method. "]m" finds the next end of a method. Additionally, "[]" moves backward to the end of a function and "][" moves forward to the end of a function. The end of a function is defined by a "}" in the first column. int func1(void) { return 1; +----------> } | [] | int func2(void) | +-> { | [[ | if (flag) start +-- +-- return flag; | ][ | return 2; | +-> } ]] | | int func3(void) +----------> { return 3; } Don't forget you can also use "%" to move between matching (), {} and []. That also works when they are many lines apart. MOVING IN BRACES The "[(" and "])" commands work similar to "[{" and "]}", except that they work on () pairs instead of {} pairs. > [( < <-------------------------------- <------- if (a == b && (c == d || (e > f)) && x > y) ~ --------------> --------------------------------> > ]) MOVING IN COMMENTS To move back to the start of a comment use "[/". Move forward to the end of a comment with "]/". This only works for /* - */ comments. +-> +-> /* | [/ | * A comment about --+ [/ | +-- * wonderful life. | ]/ | */ <-+ | +-- foo = bar * 3; --+ | ]/ /* a short comment */ <-+
*29.4* Finding global identifiers You are editing a C program and wonder if a variable is declared as "int" or "unsigned". A quick way to find this is with the "[I" command. Suppose the cursor is on the word "column". Type: > [I Vim will list the matching lines it can find. Not only in the current file, but also in all included files (and files included in them, etc.). The result looks like this: structs.h ~ 1: 29 unsigned column; /* column number */ ~ The advantage over using tags or the preview window is that included files are searched. In most cases this results in the right declaration to be found. Also when the tags file is out of date. Also when you don't have tags for the included files. However, a few things must be right for "[I" to do its work. First of all, the 'include' option must specify how a file is included. The default value works for C and C++. For other languages you will have to change it. LOCATING INCLUDED FILES Vim will find included files in the places specified with the 'path' option. If a directory is missing, some include files will not be found. You can discover this with this command: > :checkpath It will list the include files that could not be found. Also files included by the files that could be found. An example of the output: --- Included files not found in path --- ~ <io.h> ~ vim.h --> ~ <functions.h> ~ <clib/exec_protos.h> ~ The "io.h" file is included by the current file and can't be found. "vim.h" can be found, thus ":checkpath" goes into this file and checks what it includes. The "functions.h" and "clib/exec_protos.h" files, included by "vim.h" are not found. Note: Vim is not a compiler. It does not recognize "#ifdef" statements. This means every "#include" statement is used, also when it comes after "#if NEVER". To fix the files that could not be found, add a directory to the 'path' option. A good place to find out about this is the Makefile. Look out for lines that contain "-I" items, like "-I/usr/local/X11". To add this directory use: > :set path+=/usr/local/X11 When there are many subdirectories, you an use the "*" wildcard. Example: > :set path+=/usr/*/include This would find files in "/usr/local/include" as well as "/usr/X11/include". When working on a project with a whole nested tree of included files, the "**" items is useful. This will search down in all subdirectories. Example: > :set path+=/projects/invent/**/include This will find files in the directories: /projects/invent/include ~ /projects/invent/main/include ~ /projects/invent/main/os/include ~ etc. There are even more possibilities. Check out the 'path' option for info. If you want to see which included files are actually found, use this command: > :checkpath! You will get a (very long) list of included files, the files they include, and so on. To shorten the list a bit, Vim shows "(Already listed)" for files that were found before and doesn't list the included files in there again. JUMPING TO A MATCH "[I" produces a list with only one line of text. When you want to have a closer look at the first item, you can jump to that line with the command: > [<Tab> You can also use "[ CTRL-I", since CTRL-I is the same as pressing <Tab>. The list that "[I" produces has a number at the start of each line. When you want to jump to another item than the first one, type the number first: > 3[<Tab> Will jump to the third item in the list. Remember that you can use CTRL-O to jump back to where you started from. RELATED COMMANDS [i only lists the first match ]I only lists items below the cursor ]i only lists the first item below the cursor FINDING DEFINED IDENTIFIERS The "[I" command finds any identifier. To find only macros, defined with "#define" use: > [D Again, this searches in included files. The 'define' option specifies what a line looks like that defines the items for "[D". You could change it to make it work with other languages than C or C++. The commands related to "[D" are: [d only lists the first match ]D only lists items below the cursor ]d only lists the first item below the cursor
*29.5* Finding local identifiers The "[I" command searches included files. To search in the current file only, and jump to the first place where the word under the cursor is used: > gD Hint: Goto Definition. This command is very useful to find a variable or function that was declared locally ("static", in C terms). Example (cursor on "counter"): +-> static int counter = 0; | | int get_counter(void) gD | { | ++counter; +-- return counter; } To restrict the search even further, and look only in the current function, use this command: > gd This will go back to the start of the current function and find the first occurrence of the word under the cursor. Actually, it searches backwards to an empty line above the a "{" in the first column. From there it searches forward for the identifier. Example (cursor on "idx"): int find_entry(char *name) { +-> int idx; | gd | for (idx = 0; idx < table_len; ++idx) | if (strcmp(table[idx].name, name) == 0) +-- return idx; }
*usr_30.txt* For Vim version 6.1. Last change: 2001 Oct 23 Editing programs Vim has various commands that aid in writing computer programs. Compile a program and directly jump to reported errors. Automatically set the indent for many languages and format comments. |30.1| Compiling |30.2| Indenting C files |30.3| Automatic indenting |30.4| Other indenting |30.5| Tabs and spaces |30.6| Formatting comments
*30.1* Compiling Vim has a set of so called "quickfix" commands. They enable you to compile a program from within Vim and then go through the errors generated and fix them (hopefully). You can then recompile and fix any new errors that are found until finally your program compiles without any error. The following command runs the program "make" (supplying it with any argument you give) and captures the results: > :make {arguments} If errors were generated, they are captured and the editor positions you where the first error occurred. Take a look at an example ":make" session.  After typing ":make" the screen looks like this: :!make | &tee /tmp/vim215953.err ~ gcc -g -Wall -o prog main.c sub.c ~ main.c: In function 'main': ~ main.c:6: too many arguments to function 'do_sub' ~ main.c: At top level: ~ main.c:10: parse error before '}' ~ make: *** [prog] Error 1 ~ 2 returned ~ "main.c" 11L, 111C ~ (3 of 6): too many arguments to function 'do_sub' ~ Hit ENTER or type command to continue ~ From this you can see that you have errors in the file "main.c". When you press Enter, Vim displays the file "main.c", with the cursor positioned on line 6, the first line with an error. You did not need to specify the file or the line number, Vim knew where to go by looking in the error messages. +---------------------------------------------------+ |int main() | |{ | | int i=3; | cursor -> | do_sub("foo"); | | ++i; | | return (0); | |} | |} | | ~ | |(3 of 12): too many arguments to function 'do_sub' | +---------------------------------------------------+ The following command goes to where the next error occurs: > :cnext Vim jumps to line 10, the last line in the file, where there is an extra '}'. When there is not enough room, Vim will shorten the error message. To see the whole message use: > :cc You can get an overview of all the error messages with the ":clist" command. The output looks like this: > :clist < 3 main.c: 6:too many arguments to function 'do_sub' ~ 5 main.c: 10:parse error before '}' ~ Only the lines where Vim recognized a file name and line number are listed here. It assumes those are the interesting lines and the rest is just boring messages. However, sometimes unrecognized lines do contain something you want to see. Output from the linker, for example, about an undefined function. To see all the messages add a "!" to the command: > :clist! < 1 gcc -g -Wall -o prog main.c sub.c ~ 2 main.c: In function 'main': ~ 3 main.c:6: too many arguments to function 'do_sub' ~ 4 main.c: At top level: ~ 5 main.c:10: parse error before '}' ~ 6 make: *** [prog] Error 1 ~ Vim will highlight the current error. To go back to the previous error, use: > :cprevious Other commands to move around in the error list: :cfirst to first error :clast to last error :cc 3 to error nr 3 USING ANOTHER COMPILER The name of the program to run when the ":make" command is executed is defined by the 'makeprg' option. Usually this is set to "make", but Visual C++ users should set this to "nmake" by executing the following command: > :set makeprg=nmake You can also include arguments in this option. Special characters need to be escaped with a backslash. Example: > :set makeprg=nmake\ -f\ project.mak You can include special Vim keywords in the command specification. The % character expands to the name of the current file. So if you execute the command: > :set makeprg=make\ % When you are editing main.c, then ":make" executes the following command: > make main.c This is not too useful, so you will refine the command a little and use the :r (root) modifier: > :set makeprg=make\ %:r.o Now the command executed is as follows: > make file.o More about these modifiers here: |filename-modifiers|. OLD ERROR LISTS Suppose you ":make" a program. There is an warning message in one file and an error message in another. You fix the error and use ":make" again to check if it was really fixed. Now you want to look at the warning message. It doesn't show up in the last error list, since the file with the warning wasn't compiled again. You can go back to the previous error list with: > :colder Then use ":clist" and "cc {nr}" to jump to the place with the warning. To go forward to the next error list: > :cnewer Vim remembers ten error lists. SWITCHING COMPILERS You have to tell Vim what format the error messages are that your compiler produces. This is done with the 'errorformat' option. The syntax of this option is quite complicated and it can be made to fit almost any compiler. You can find the explanation here: |errorformat|. You might be using various different compilers. Setting the 'makeprg' option, and especially the 'errorformat' each time is not easy. Vim offers a simple method for this. For example, to switch to using the Microsoft Visual C++ compiler: > :compiler msvc This will find the Vim script for the "msvc" compiler and set the appropriate options. You can write your own compiler files. See |write-compiler-plugin|. OUTPUT REDIRECTION The ":make" command redirects the output of the executed program to an error file. How this works depends on various things, such as the 'shell'. If your ":make" command doesn't capture the output, check the 'makeef' and 'shellredir' options. The 'shellquote' and 'shellxquote' options might also matter. In case you can't get ":make" to redirect the file for you, an alternative is to compile the program in another window and redirect the output into a file. Then have Vim read this file with: > :cfile {filename} Jumping to errors will work like with the ":make" command.
*30.2* Indenting C files A program is much easier to understand when the lines have been properly indented. Vim offers various ways to make this less work. For C programs set the 'cindent' option. Vim knows a lot about C programs and will try very hard to automatically set the indent for you. Set the 'shiftwidth' option to the amount of spaces you want for a deeper level. Four spaces will work fine. One ":set" command will do it: > :set cindent shiftwidth=4 With this option enabled, when you type something such as "if (x)", the next line will automatically be indented an additional level. if (flag) Automatic indent ---> do_the_work(); Automatic unindent <-- if (other_flag) { Automatic indent ---> do_file(); keep indent do_some_more(); Automatic unindent <-- } When you type something in curly braces ({}), the text will be indented at the start and unindented at the end. The unindenting will happen after typing the '}', since Vim can't guess what you are going to type. One side effect of automatic indentation is that it helps you catch errors in your code early. When you type a } to finish a function, only to find that the automatic indentation gives it more indent than what you expected, there is probably a } missing. Use the "%" command to find out which { matches the } you typed. A missing ) and ; also cause extra indent. Thus if you get more white space than you would expect, check the preceding lines. When you have code that is badly formatted, or you inserted and deleted lines, you need to re-indent the lines. The "=" operator does this. The simplest form is: > == This indents the current line. Like with all operators, there are three ways to use it. In Visual mode "=" indents the selected lines. A useful text object is "a{" This selects the current {} block. Thus, to re-indent the code code block the cursor is in: > =a{ I you have really badly indented code, you can re-indent the whole file with: > gg=G However, don't do this in files that have been carefully indented manually. The automatic indenting does a good job, but in some situations you might want to overrule it. SETTING INDENT STYLE Different people have different styles of indentation. By default Vim does a pretty good job of indenting in a way that 90% of programmers do. There are different styles, however; so if you want to, you can customize the indentation style with the 'cinoptions' option. By default 'cinoptions' is empty and Vim uses the default style. You can add various items where you want something different. For example, to make curly braces be placed like this: if (flag) ~ { ~ i = 8; ~ j = 0; ~ } ~ Use this command: > :set cinoptions+={2 There are many of these items. See |cinoptions-values|.
*30.3* Automatic indenting You don't want to switch on the 'cindent' option manually every time you edit a C file. This is how you make it work automatically: > :filetype indent on Actually, this does a lot more than switching on 'cindent' for C files. First of all, it enables detecting the type of a file. That's the same as what is used for syntax highlighting. When the filetype is known, Vim will search for an indent file for this type of file. The Vim distribution includes a number of these for various programming languages. This indent file will then prepare for automatic indenting specifically for this file. If you don't like the automatic indenting, you can switch it off again: > :filetype indent off If you don't like the indenting for one specific type of file, this is how you avoid it. Create a file with just this one line: > :let b:did_indent = 1 Now you need to write this in a file with a specific name: {directory}/indent/{filetype}.vim The {filetype} is the name of the file type, such as "cpp" or "java". You can see the exact name that Vim detected with this command: > :set filetype In this file the output is: filetype=help ~ This you would use "help" for {filetype}. For the {directory} part you need to use your runtime directory. Look at the output of this command: > set runtimepath Now use the first item, the name before the first comma. Thus if the output looks like this: runtimepath=~/.vim,/usr/local/share/vim/vim60/runtime,~/.vim/after ~ You use "~/.vim" for {directory}. Then the resulting file name is: ~/.vim/indent/help.vim ~ Instead of switching the indenting off, you could write your own indent file. How to do that is explained here: |indent-expression|.
*30.4* Other indenting The most simple form of automatic indenting is with the 'autoindent' option. It uses the indent from the previous line. A bit smarter is the 'smartindent' option. This is useful for languages where no indent file is available. 'smartindent'is not as smart as 'cindent', but smarter than 'autoindent'. With 'smartindent' set, an extra level of indentation is added for each { and removed for each }. An extra level of indentation will also be added for any of the words in the 'cinwords' option. Lines that begin with # are treated specially: all indentation is removed. This is done so that preprocessor directives will all start in column 1. The indentation is restored for the next line. CORRECTING INDENTS When you are using 'autoindent' or 'smartindent' to get the indent of the previous line, there will be many times when you need to add or remove one 'shiftwidth' worth of indent. A quick way to do this is using the CTRL-D and CTRL-T commands in Insert mode. For example, you are typing a shell script that is supposed to look like this: if test -n a; then ~ echo a ~ echo "-------" ~ fi ~ Start off by setting these option: > :set autoindent shiftwidth=3 You start by typing the first line, <Enter> and the start of the second line: if test -n a; then ~ echo ~ Now you see that you need an extra indent. Type CTRL-T. The result: if test -n a; then ~ echo ~ The CTRL-T command, in Insert mode, adds one 'shiftwidth' to the indent, no matter where in the line you are. You continue typing the second line, <Enter> and the third line. This time the indent is OK. Then <Enter> and the last line. Now you have this: if test -n a; then ~ echo a ~ echo "-------" ~ fi ~ To remove the superfluous indent in the last line press CTRL-D. This deletes one 'shiftwidth' worth of indent, no matter where you are in the line. When you are in Normal mode, you can use the ">>" and "<<" commands to shift lines. ">" and "<" are operators, thus you have the usual three ways to specify the lines you want to indent. A useful combination is: > >i{ This adds one indent to the current block of lines, inside {}. The { and } lines themselves are left unmodified. ">a{" includes them. In this example the cursor is on "printf": original text after ">i{" after ">a{" if (flag) if (flag) if (flag) ~ { { { ~ printf("yes"); printf("yes"); printf("yes"); ~ flag = 0; flag = 0; flag = 0; ~ } } } ~
*30.5* Tabs and spaces 'tabstop' is set to eight by default. Although you can change it, you quickly run into trouble later. Other programs won't know what tabstop value you used. They probably use the default value of eight, and your text suddenly looks very different. Also, most printers use a fixed tabstop value of eight. Thus it's best to keep 'tabstop' alone. (If you edit a file which was written with a different tabstop setting, see |25.3| for how to fix that.) For indenting lines in a program, using a multiple of eight spaces makes you quickly run into the right border of the window. Using a single space doesn't provide enough visual difference. Many people prefer to use four spaces, a good compromise. Since a <Tab> is eight spaces and you want to use an indent of four spaces, you can't use a <Tab> character to make your indent. There are two ways to handle this: 1. Use a mix of <Tab> and space characters. Since a <Tab> takes the place of eight spaces, you have fewer characters in your file. Inserting a <Tab> is quicker than eight spaces. Backspacing works faster as well. 2. Use spaces only. This avoids the trouble with programs that use a different tabstop value. Fortunately, Vim supports both methods quite well. SPACES AND TABS If you are using a combination of tabs and spaces, you just edit normally. The Vim defaults do a fine job of handling things. You can make life a little easier by setting the 'softtabstop' option. This option tells Vim to make the Tab key look and feel as if tabs were set at the value of 'softtabstop', but actually use a combination of tabs and spaces. After you execute the following command, every time you press the Tab key the cursor moves to the next 4-column boundary: > :set softtabstop=4 When you start in the first column and press <Tab>, you get 4 spaces inserted in your text. The second time, Vim takes out the 4 spaces and puts in a <Tab> (thus taking you to column 8). Thus Vim uses as many <Tab>s as possible, and then fills up with spaces. When backspacing it works the other way around. A <BS> will always delete the amount specified with 'softtabstop'. Then <Tabs>gt; are used as many as possible and spaces to fill the gap. The following shows what happens pressing <Tab> a few times, and then using <BS>. A "." stands for a space and "------->" for a <Tab>. type result ~ <Tab> .... <Tab><Tab> -------> <Tab><Tab><Tab> ------->.... <Tab><Tab><Tab><BS> -------> <Tab><Tab><Tab><BS><BS> .... An alternative is to use the 'smarttab' option. When it's set, Vim uses 'shiftwidth' for a <Tab> typed in the indent of a line, and a real <Tab> when typed after the first non-blank character. However, <BS> doesn't work like with 'softtabstop'. JUST SPACES If you want absolutely no tabs in your file, you can set the 'expandtab' option: > :set expandtab When this option is set, the <Tab> key inserts a series of spaces. Thus you get the same amount of white space as if a <Tab> character was inserted, but there isn't a real <Tab> character in your file. The backspace key will delete each space by itself. Thus after typing one <Tab> you have to press the <BS> key up to eight times to undo it. If you are in the indent, pressing CTRL-D will be a lot quicker. CHANGING TABS IN SPACES (AND BACK) Setting 'expandtab' does not affect any existing tabs. In other words, any tabs in the document remain tabs. If you want to convert tabs to spaces, use the ":retab" command. Use these commands: > :set expandtab :%retab Now Vim will have changed all indents to use spaces instead of tabs. However, all tabs that come after a non-blank character are kept. If you want these to be converted as well, add a !: > :%retab! This is a little bit dangerous, because it can also change tabs inside a string. To check if these exist, you could use this: > /"[^"\t]*\t[^"]*" It's recommended not to use hard tabs inside a string. Replace them with "\t" to avoid trouble. The other way around works just as well: > :set noexpandtab :%retab!
*30.6* Formatting comments One of the great things about Vim is that it understands comments. You can ask Vim to format a comment and it will do the right thing. Suppose, for example, that you have the following comment: /* ~ * This is a test ~ * of the text formatting. ~ */ ~ You then ask Vim to format it by positioning the cursor at the start of the comment and type: > gq]/ "gq" is the operator to format text. "]/" is the motion that takes you to the end of a comment. The result is: /* ~ * This is a test of the text formatting. ~ */ ~ Notice that Vim properly handled the beginning of each line. An alternative is to select the text that is to be formatted in Visual mode and type "gq". To add a new line to the comment, position the cursor on the middle line and press "o". The result looks like this: /* ~ * This is a test of the text formatting. ~ * ~ */ ~ Vim has automatically inserted a star and a space for you. Now you can type the comment text. When it gets longer than 'textwidth', Vim will break the line. Again, the star is inserted automatically: /* ~ * This is a test of the text formatting. ~ * Typing a lot of text here will make Vim ~ * break ~ */ ~ For this to work some flags must be present in 'formatoptions': r insert the star when typing <Enter> in Insert mode o insert the star when using "o" or "O" in Normal mode c break comment text according to 'textwidth' See |fo-table| for more flags. DEFINING A COMMENT The 'comments' option defines what a comment looks like. Vim distinguishes between a single-line comment and a comment that has a different start, end and middle part. Many single-line comments start with a specific character. In C++ // is used, in Makefiles #, in Vim scripts ". For example, to make Vim understand C++ comments: > :set comments=:// The colon separates the flags of an item from the text by which the comment is recognized. The general form of an item in 'comments' is: {flags}:{text} The {flags} part can be empty, as in this case. Several of these items can be concatenated, separated by commas. This allows recognizing different types of comments at the same time. For example, let's edit an e-mail message. When replying, the text that others wrote is preceded with ">" and "!" characters. This command would work: > :set comments=n:>,n:! There are two items, one for comments starting with ">" and one for comments that start with "!". Both use the flag "n". This means that these comments nest. Thus a line starting with ">" may have another comment after the ">". This allows formatting a message like this: > ! Did you see that site? ~ > ! It looks really great. ~ > I don't like it. The ~ > colors are terrible. ~ What is the URL of that ~ site? ~ Try setting 'textwidth' to a different value, e.g., 80, and format the text by Visually selecting it and typing "gq". The result is: > ! Did you see that site? It looks really great. ~ > I don't like it. The colors are terrible. ~ What is the URL of that site? ~ You will notice that Vim did not move text from one type of comment to another. The "I" in the second line would have fit at the end of the first line, but since that line starts with "> !" and the second line with ">", Vim knows that this is a different kind of comment. A THREE PART COMMENT A C comment starts with "/*", has "*" in the middle and "*/" at the end. The entry in 'comments' for this looks like this: > :set comments=s1:/*,mb:*,ex:*/ The start is defined with "s1:/*". The "s" indicates the start of a three-piece comment. The colon separates the flags from the text by which the comment is recognized: "/*". There is one flag: "1". This tells Vim that the middle part has an offset of one space. The middle part "mb:*" starts with "m", which indicates it is a middle part. The "b" flag means that a blank must follow the text. Otherwise Vim would consider text like "*pointer" also to be the middle of a comment. The end part "ex:*/" has the "e" for indentification. The "x" flag has a special meaning. It means that after Vim automatically inserted a star, typing / will remove the extra space. For more details see |format-comments|.
*usr_31.txt* For Vim version 6.1. Last change: 2001 Nov 02 Exploiting the GUI Vim works well in a terminal, but the GUI has a few extra items. A file browser can be used for commands that use a file. A dialog to make a choice between alternatives. Use keyboard shortcuts to access menu items quickly. |31.1| The file browser |31.2| Confirmation |31.3| Menu shortcuts |31.4| Vim window position and size |31.5| Various
*31.1* The file browser When using the File/Open... menu you get a file browser. This makes it easier to find the file you want to edit. But what if you want to split a window to edit another file? There is no menu entry for this. You could first use Window/Split and then File/Open..., but that's more work. Since you are typing most commands in Vim, opening the file browser with a typed command is possible as well. To make the split command use the file browser, prepend "browse": > :browse split Select a file and then the ":split" command will be executed with it. If you cancel the file dialog nothing happens, the window isn't split. You can also specify a file name argument. This is used to tell the file browser where to start. Example: > :browse split /etc The file browser will pop up, starting in the directory "/etc". The ":browse" command can be prepended to just about any command that opens a file. If no directory is specified, Vim will decide where to start the file browser. By default it uses the same directory as the last time. Thus when you used ":browse split" and selected a file in "/usr/local/share", the next time you use a ":browse" it will start in "/usr/local/share" again. This can be changed with the 'browsedir' option. It can have one of three values: last Use the last directory browsed (default) buffer Use the same directory as the current buffer current use the current directory For example, when you are in the directory "/usr", editing the file "/usr/local/share/readme", then the command: > :set browsedir=buffer :browse edit Will start the browser in "/usr/local/share". Alternatively: > :set browsedir=current :browse edit Will start the browser in "/usr". Note: To avoid using the mouse, most file browsers offer using key presses to navigate. Since this is different for every system, it is not explained here. Vim uses a standard browser when possible, your system documentation should contain an explanation on the keyboard shortcuts somewhere. When you are not using the GUI version, you could use the file explorer window to select files like in a file browser. However, this doesn't work for the ":browse" command. See |file-explorer|.
*31.2* Confirmation Vim protects you from accidentally overwriting a file and other ways to lose changes. If you do something that might be a bad thing to do, Vim produces an error message and suggests appending ! if you really want to do it. To avoid retyping the command with the !, you can make Vim give you a dialog. You can then press "OK" or "Cancel" to tell Vim what you want. For example, you are editing a file and made changes to it. You start editing another file with: > :confirm edit foo.txt Vim will pop up a dialog that looks something like this: +-----------------------------------+ | | | ? Save changes to "bar.txt"? | | | | YES NO CANCEL | +-----------------------------------+ Now make your choice. If you do want to save the changes, select "YES". If you want to lose the changes for ever: "NO". If you forgot what you were doing and want to check what really changed use "CANCEL". You will be back in the same file, with the changes still there. Just like ":browse", the ":confirm" command can be prepended to most commands that edit another file. They can also be combined: > :confirm browse edit This will produce a dialog when the current buffer was changed. Then it will pop up a file browser to select the file to edit. Note: In the dialog you can use the keyboard to select the choice. Typically the <Tab> key and the cursor keys change the choice. Pressing <Enter> selects the choice. This depends on the system though. When you are not using the GUI, the ":confirm" command works as well. Instead of popping up a dialog, Vim will print the message at the bottom of the Vim window and ask you to press a key to make a choice. > :confirm edit main.c < Save changes to "Untitled"? ~ [Y]es, (N)o, (C)ancel: ~ You can now press the single key for the choice. You don't have to press <Enter>, unlike other typing on the command line.
*31.3* Menu shortcuts The keyboard is used for all Vim commands. The menus provide a simple way to select commands, without knowing what they are called. But you have to move your hand from the keyboard and grab the mouse. Menus can often be selected with keys as well. This depends on your system, but most often it works this way. Use the <Alt> key in combination with the underlined letter of a menu. For example, <A-w> (<Alt> and w) pops up the Window menu. In the Window menu, the "split" item has the p underlined. To select it, let go of the <Alt> key and press p. After the first selection of a menu with the <Alt> key, you can use the cursor keys to move through the menus. <Left> selects a submenu and <Right> closes it. <Esc> also closes a menu. <Enter> selects a menu item. There is a conflict between using the <Alt> key to select menu items, and using <Alt> key combinations for mappings. The 'winaltkeys' option tells Vim what it should do with the <Alt> key. The default value "menu" is the smart choice: If the key combination is a menu shortcut it can't be mapped. All other keys are available for mapping. The value "no" doesn't use any <Alt> keys for the menus. Thus you must use the mouse for the menus, and all <Alt> keys can be mapped. The value "yes" means that Vim will use any <Alt> keys for the menus. Some <Alt> key combinations may also do other things than selecting a menu.
*31.4* Vim window position and size To see the current Vim window position on the screen use: > :winpos This will only work in the GUI. The output may look like this: Window position: X 272, Y 103 ~ The position is given in screen pixels. Now you can use the numbers to move Vim somewhere else. For example, to move it to the left a hundred pixels: > :winpos 172 103 < Note: There may be a small offset between the reported position and where the window moves. This is because of the border around the window. This is added by the window manager. You can use this command in your startup script to position the window at a specific position. The size of the Vim window is computed in characters. Thus this depends on the size of the font being used. You can see the current size with this command: > :set lines columns To change the size set the 'lines' and/or 'columns' options to a new value: > :set lines=50 :set columns=80 Obtaining the size works in a terminal just like in the GUI. Setting the size is not possible in most terminals. You can start the X-Windows version of gvim with an argument to specify the size and position of the window: > gvim -geometry {width}x{height}+{x_offset}+{y_offset} {width} and {height} are in characters, {x_offset} and {y_offset} are in pixels. Example: > gvim -geometry 80x25+100+300
*31.5* Various You can use gvim to edit an e-mail message. In your e-mail program you must select gvim to be the editor for messages. When you try that, you will see that it doesn't work: The mail program thinks that editing is finished, while gvim is still running! What happens is that gvim disconnects from the shell it was started in. That is fine when you start gvim in a terminal, so that you can do other work in that terminal. But when you really want to wait for gvim to finish, you must prevent it from disconnecting. The "-f" argument does this: > gvim -f file.txt The "-f" stands for foreground. Now Vim will block the shell it was started in until you finish editing and exit. DELAYED START OF THE GUI On Unix it's possible to first start Vim in a terminal. That's useful if you do various tasks in the same shell. If you are editing a file and decide you want to use the GUI after all, you can start it with: > :gui Vim will open the GUI window and no longer use the terminal. You can continue using the terminal for something else. The "-f" argument is used here to run the GUI in the foreground. You can also use ":gui -f". THE GVIM STARTUP FILE When gvim starts, it reads the gvimrc file. That's similar to the vimrc file used when starting Vim. The gvimrc file can be used for settings and commands that are only to be used when the GUI is going to be started. For example, you can set the 'lines' variable to set a different window size: > :set lines=55 You don't want to do this in a terminal, since it's size is fixed (except for an xterm that supports resizing). The gvimrc file is searched for in the same locations as the vimrc file. Normally it's name is "~/.gvimrc" for Unix and "$VIM/_gvimrc" for MS-Windows. If for some reason you don't want to use the normal gvimrc file, you can specify another one with the "-U" argument: > gvim -U thisrc ... That allows starting gvim for different kinds of editing. You could set another font size, for example. To completely skip reading a gvimrc file: > gvim -U NONE ...
*usr_40.txt* For Vim version 6.1. Last change: 2001 Sep 03 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
*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.  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 a good choice 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 a "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 mode, etc. A blank is used for a mapping defined with ":map", thus effective in both Normal and Visual mode. One useful purpose of listing the mapping is to check if special keys in <> form have been recognized (this only works when color is supported). For example, when <Esc> is displayed in color, it stands for the escape character. When it has the same color as the other text, it is five characters. REMAPPING The result of a mapping is inspected for other mappings in it. For example, the mappings for <F2> above could be shortened to: > :map <F2> G<F3> :imap <F2> <Esc><F3> :map <F3> oDate: <Esc>:read !date<CR>kJ For Normal mode <F2> is mapped to go to the last line, and then behave like <F3> was pressed. In Insert mode <F2> stops Insert mode with <Esc> and then also uses <F3>. Then <F3> is mapped to do the actual work. Suppose you hardly ever use Ex mode, and want to use the "Q" command to format text (this was so in old versions of Vim). This mapping will do it: > :map Q gq But, in rare cases you need to use Ex mode anyway. Let's map "gQ" to Q, so that you can still go to Ex mode: > :map gQ Q What happens now is that when you type "gQ" it is mapped to "Q". So far so good. But then "Q" is mapped to "gq", thus typing "gQ" results in "gq", and you don't get to Ex mode at all. To avoid keys to be mapped again, use the ":noremap" command: > :noremap gQ Q Now Vim knows that the "Q" is not to be inspected for mappings that apply to it. There is a similar command for every mode: :noremap Normal, Visual and Operator-pending :vnoremap Visual :nnoremap Normal :onoremap Operator-pending :noremap! Insert and Command-line :inoremap Insert :cnoremap Command-line RECURSIVE MAPPING When a mapping triggers itself, it will run forever. This can be used to repeat an action an unlimited number of times. For example, you have a list of files that contain a version number in the first line. You edit these files with "vim *.txt". You are now editing the first file. Define this mapping: > :map ,, :s/5.1/5.2/<CR>:wnext<CR>,, Now you type ",,". This triggers the mapping. It replaces "5.1" with "5.2" in the first line. Then it does a ":wnext" to write the file and edit the next one. The mapping ends in ",,". This triggers the same mapping again, thus doing the substitution, etc. This continues until there is an error. In this case it could be a file where the substitute command doesn't find a match for "5.1". You can then make a change to insert "5.1" and continue by typing ",," again. Or the ":wnext" fails, because you are in the last file in the list. When a mapping runs into an error halfway, the rest of the mapping is discarded. CTRL-C interrupts the mapping (CTRL-Break on MS-Windows). DELETE A MAPPING To remove a mapping use the ":unmap" command. Again, the mode the unmapping applies to depends on the command used: :unmap Normal, Visual and Operator-pending :vunmap Visual :nunmap Normal :ounmap Operator-pending :unmap! Insert and Command-line :iunmap Insert :cunmap Command-line There is a trick to define a mapping that works in Normal and Operator-pending mode, but not in Visual mode. First define it for all three modes, then delete it for Visual mode: > :map <C-A> /---><CR> :vunmap <C-A> Notice that the five characters "<C-A>" stand for the single key CTRL-A. To remove all mappings use the |:mapclear| command. You can guess the variations for different modes by now. Be careful with this command, it can't be undone. SPECIAL CHARACTERS The ":map" command can be followed by another command. A | character separates the two commands. This also means that a | character can't be used inside a map command. To include one, use <Bar> (five characters). Example: > :map <F8> :write <Bar> !checkin %<CR> The same problem applies to the ":unmap" command, with the addition that you have to watch out for trailing white space. These two commands are different: > :unmap a | unmap b :unmap a| unmap b The first command tries to unmap "a ", with a trailing space. When using a space inside a mapping, use <Space> (seven characters): > :map <Space> W This makes the spacebar move a blank-separated word forward. It is not possible to put a comment after a mapping, because the " character is considered to be part of the mapping. MAPPINGS AND ABBREVIATIONS Abbreviations are a lot like Insert mode mappings. The arguments are handled in the same way. The main difference is the way they are triggered. An abbreviation is triggered by typing a non-word character after the word. A mapping is triggered when typing the last character. Another difference is that the characters you type for an abbreviation are inserted in the text while you type them. When the abbreviation is triggered these characters are deleted and replaced by what the abbreviation produces. When typing the characters for a mapping, nothing is inserted until you type the last character that triggers it. If the 'showcmd' option is set, the typed characters are displayed in the last line of the Vim window.  Suppose you have done two mappings: > :imap aa foo :imap aaa bar Now, when you type "aa", Vim doesn't know if it should apply the first or the second mapping. It waits for another character to be typed. If it is an "a", the second mapping is applied and results in "bar". If it is a space, for example, the first mapping is applied, resulting in "foo", and then the space is inserted. ADDITIONALLY... The <script> keyword can be used to make a mapping local to a script. See |:map-<script>|. The <buffer> keyword can be used to make a mapping local to a specific buffer. See |:map-<buffer>| The <unique> keyword can be used to make defining a new mapping fail when it already exists. Otherwise a new mapping simply overwrites the old one. See |:map-<unique>|. To make a key do nothing, map it to <Nop> (five characters). This will make the <F7> key do nothing at all: > :map <F7> <Nop>| map! <F7> <Nop> There must be no space after <Nop>.
*40.2* Defining command-line commands The Vim editor enables you to define your own commands. You execute these commands just like any other Command-line mode command. To define a command, use the ":command" command, as follows: > :command DeleteFirst 1delete Now when you execute the command ":DeleteFirst" Vim excutes ":1delete", which deletes the first line. Note: User-defined commands must start with a capital letter. You cannot use ":X", ":Next" and ":Print". The underscore cannot be used! You can use digits, but this is discouraged. To list the user-defined commands, execute the following command: > :command Just like with the builtin commands, the user defined commands can be abbreviated. You need to type just enough to distinguish the command from another. Command line completion can be used to get the full name. NUMBER OF ARGUMENTS User-defined commands can take a series of arguments. The number of arguments must be specified by the -nargs option. For instance, the example :DeleteFirst command takes no arguments, so you could have defined it as follows: > :command -nargs=0 DeleteFirst 1delete However, because zero arguments is the default, you do not need to add "-nargs=0". The other values of -nargs are as follows: -nargs=0 No arguments -nargs=1 One argument -nargs=* Any number of arguments -nargs=? Zero or one argument -nargs=+ One or more arguments USING THE ARGUMENTS Inside the command definition, the arguments are represented by the <args> keyword. For example: > :command -nargs=+ Say :echo "<args>" Now when you type > :Say Hello World Vim echoes "Hello World". However, if you add a double quote, it won't work. For example: > :Say he said "hello" To get special characters turned into a string, properly escaped to use as an expression, use "<q-args>": > :command -nargs=+ Say :echo <q-args> Now the above ":Say" command will result in this to be executed: > :echo "he said \"hello\"" The <f-args> keyword contains the same information as the <args> keyword, except in a format suitable for use as function call arguments. For example: > :command -nargs=* DoIt :call AFunction(<f-args>) :DoIt a b c Execute the following command: > :call AFunction("a", "b", "c") LINE RANGE Some commands take a range as their argument. To tell Vim that you are defining such a command, you need to specify a -range option. The values for this option are as follows: -range Range is allowed; default is the current line. -range=% Range is allowed; default is the whole file. -range={count} Range is allowed; the last number in it is used as a single number whose default is {count}. When a range is specified, the keywords <line1> and <line2> get the values of the first and last line in the range. For example, the following command defines the SaveIt command, which writes out the specified range to the file "save_file": > :command -range=% SaveIt :<line1>,<line2>write! save_file OTHER OPTIONS Some of the other options and keywords are as follows: -count={number} The command can take a count whose default is {number}. The resulting count can be used through the <count> keyword. -bang You can use a !. If present, using <bang> will result in a !. -register You can specify a register. (The default is the unnamed register.) The register specification is available as <reg> (a.k.a. <register>). -complete={type} Type of command-line completion used. See |:command-completion| for the list of possible values. -bar The command can be followed by | and another command, or " and a comment. -buffer The command is only available for the current buffer. Finally, you have the <lt> keyword. It stands for the character <. Use this to escape the special meaning of the <> items mentioned. REDEFINING AND DELETING To redefine the same command use the ! argument: > :command -nargs=+ Say :echo "<args>" :command! -nargs=+ Say :echo <q-args> To delete a user command use ":delcommand". It takes a single argument, which is the name of the command. Example: > :delcommand SaveIt To delete all the user commands: > :comclear Careful, this can't be undone! More details about all this in the reference manual: |user-commands|.
*40.3* Autocommands An autocommand is a command that is executed automatically in response to some event, such as a file being read or written or a buffer change. Through the use of autocommands you can train Vim to edit compressed files, for example. That is used in the |gzip| plugin. Autocommands are very powerful. Use them with care and they will help you avoid typing many commands. Use them carelessly and they will cause a lot of trouble. Suppose you want to replace a date stamp on the end of a file every time it is written. First you define a function: > :function DateInsert() : $delete : read !date :endfunction You want this function to be called each time, just before a file is written. This will make that happen: > :autocmd FileWritePre * call DateInsert() "FileWritePre" is the event for which this autocommand is triggered: Just before (pre) writing a file. The "*" is a pattern to match with the file name. In this case it matches all files. With this command enabled, when you do a ":write", Vim checks for any matching FileWritePre autocommands and executes them, and then it performs the ":write". The general form of the :autocmd command is as follows: > :autocmd [group] {events} {file_pattern} [nested] {command} The [group] name is optional. It is used in managing and calling the commands (more on this later). The {events} parameter is a list of events (comma separated) that trigger the command. {file_pattern} is a filename, usually with wildcards. For example, using "*.txt" makes the autocommand be used for all files whose name end in ".txt". The optional [nested] flag allows for nesting of autocommands (see below), and finally, {command} is the command to be executed. EVENTS One of the most useful events is BufReadPost. It is triggered after a new file is being edited. It is commonly used to set option values. For example, you know that "*.gsm" files are GNU assembly language. To get the syntax file right, define this autocommand: > :autocmd BufReadPost *.gsm set filetype=asm If Vim is able to detect the type of file, it will set the 'filetype' option for you. This triggers the Filetype event. Use this to do something when a certain type of file is edited. For example, to load a list of abbreviations for text files: > :autocmd Filetype text source ~/.vim/abbrevs.vim When starting to edit a new file, you could make Vim insert a skeleton: > :autocmd BufNewFile *.[ch] 0read ~/skeletons/skel.c See |autocmd-events| for a complete list of events. PATTERNS The {file_pattern} argument can actually be a comma-separated list of file patterns. For example: "*.c,*.h" matches files ending in ".c" and ".h". The usual file wildcards can be used. Here is a summary of the most often used ones: * Match any character any number of times ? Match any character once [abc] Match the character a, b or c . Matches a dot a{b,c} Matches "ab" and "ac" When the pattern includes a slash (/) Vim will compare directory names. Without the slash only the last part of a file name is used. For example, "*.txt" matches "/home/biep/readme.txt". The pattern "/home/biep/*" would also match it. But "home/foo/*.txt" wouldn't. When including a slash, Vim matches the pattern against both the full path of the file ("/home/biep/readme.txt") and the relative path (e.g., "biep/readme.txt"). Note: When working on a system that uses a backslash as file separater, such as MS-Windows, you still use forward slashes in autocommands. This makes it easier to write the pattern, since a backslash has a special meaning. It also makes the autocommands portable. DELETING To delete an autocommand, use the same command as what it was defined with, but leave out the {command} at the end and use a !. Example: > :autocmd! FileWritePre * This will delete all autocommands for the "FileWritePre" event that use the "*" pattern. LISTING To list all the currently defined autocommands, use this: > :autocmd The list can be very long, especially when filetype detection is used. To list only part of the commands, specify the group, event and/or pattern. For example, to list all BufNewFile autocommands: > :autocmd BufNewFile To list all autocommands for the pattern "*.c": > :autocmd * *.c Using "*" for the event will list all the events. To list all autocommands for the cprograms group: > :autocmd cprograms GROUPS The {group} item, used when defining an autocommand, groups related autocommands together. This can be used to delete all the autocommands in a certain group, for example. When defining several autocommands for a certain group, use the ":augroup" command. For example, let's define autocommands for C programs: > :augroup cprograms : autocmd BufReadPost *.c,*.h :set sw=4 sts=4 : autocmd BufReadPost *.cpp :set sw=3 sts=3 :augroup END This will do the same as: > :autocmd cprograms BufReadPost *.c,*.h :set sw=4 sts=4 :autocmd cprograms BufReadPost *.cpp :set sw=3 sts=3 To delete all autocommands in the "cprograms" group: > :autocmd! cprograms NESTING Generally, commands executed as the result of an autocommand event will not trigger any new events. If you read a file in response to a FileChangedShell event, it will not trigger the autocommands that would set the syntax, for example. To make the events triggered, add the "nested" argument: > :autocmd FileChangedShell * nested edit EXECUTING AUTOCOMMANDS It is possible to trigger an autocommand by pretending an event has occurred. This is useful to have one autocommand trigger another one. Example: > :autocmd BufReadPost *.new execute "doautocmd BufReadPost " . expand("<afile>:r") This defines an autocommand that is triggered when a new file has been edited. The file name must end in ".new". The ":execute" command uses expression evaluation to form a new command and execute it. When editing the file "tryout.c.new" the executed command will be: > :doautocmd BufReadPost tryout.c The expand() function takes the "<afile>" argument, which stands for the file name the autocommand was executed for, and takes the root of the file name with ":r". ":doautocmd" executes on the current buffer. The ":doautoall" command works like "doautocmd" except it executes on all the buffers. USING NORMAL MODE COMMANDS The commands executed by an autocommand are Command-line command. If you want to use a Normal mode command, the ":normal" command can be used. Example: > :autocmd BufReadPost *.log normal G This will make the cursor jump to the last line of *.log files when you start to edit it. Using the ":normal" command is a bit tricky. First of all, make sure its argument is a complete command, including all the arguments. When you use "i" to go to Insert mode, there must also be a <Esc> to leave Insert mode again. If you use a "/" to start a search pattern, there must be a <CR> to execute it. The ":normal" command uses all the text after it as commands. Thus there can be no | and another command following. To work around this, put the ":normal" command inside an ":execute" command. This also makes it possible to pass unprintable characters in a convenient way. Example: > :autocmd BufReadPost *.chg execute "normal ONew entry:\<Esc>" | \ 1read !date This also shows the use of a backslash to break a long command into more lines. This can be used in Vim scripts (not at the command line). When you want the autocommand do something complicated, which involves jumping around in the file and then returning to the original position, you may want to restore the view on the file. See |restore-position| for an example. IGNORING EVENTS At times, you will not want to trigger an autocommand. The 'eventignore' option contains a list of events that will be totally ignored. For example, the following causes events for entering and leaving a window to be ignored: > :set eventignore=WinEnter,WinLeave To ignore all events, use the following command: > :set eventignore=all To set it back to the normal behavior, make 'eventignore' empty: > :set eventignore=
*usr_41.txt* For Vim version 6.1. Last change: 2001 Oct 26 Write a Vim script The Vim script language is used for the startup vimrc file, syntax files, and many other things. This chapter explains the items that can be used in a Vim script. There are a lot of them, thus this is a long chapter. |41.1| Introduction |41.2| Variables |41.3| Expressions |41.4| Conditionals |41.5| Executing an expression |41.6| Using functions |41.7| Defining a function |41.8| Various remarks |41.9| Writing a plugin |41.10| Writing a filetype plugin |41.11| Writing a compiler plugin
*41.1* Introduction *vimrc-intro* *vim-script-intro* Your first experience with Vim scripts is the vimrc file. Vim reads it when it starts up and executes the commands. You can set options to values you prefer. And you can use any colon command in it (commands that start with a ":"; these are sometimes referred to as Ex commands or command-line commands). Syntax files are also Vim scripts. As are files that set options for a specific file type. A complicated macro can be defined by a separate Vim script file. You can think of other uses yourself. Let's start with a simple example: > :let i = 1 :while i < 5 : echo "count is" i : let i = i + 1 :endwhile < Note: The ":" characters are not really needed here. You only need to use them when you type a command. In a Vim script file they can be left out. We will use them here anyway to make clear these are colon commands and make them stand out from Normal mode commands. The ":let" command assigns a value to a variable. The generic form is: > :let {variable} = {expression} In this case the variable name is "i" and the expression is a simple value, the number one. The ":while" command starts a loop. The generic form is: > :while {condition} : {statements} :endwhile The statements until the matching ":endwhile" are executed for as long as the condition is true. The condition used here is the expression "i < 5". This is true when the variable i is smaller than five. The ":echo" command prints its arguments. In this case the string "count is" and the value of the variable i. Since i is one, this will print: count is 1 ~ Then there is another ":let i =" command. The value used is the expression "i + 1". This adds one to the variable i and assigns the new value to the same variable. The output of the example code is: count is 1 ~ count is 2 ~ count is 3 ~ count is 4 ~ Note: If you happen to write a while loop that keeps on running, you can interrupt it by pressing CTRL-C (CTRL-Break on MS-Windows). THREE KINDS OF NUMBERS Numbers can be decimal, hexadecimal or octal. A hexadecimal number starts with "0x" or "0X". For example "0x1f" is 31. An octal number starts with a zero. "017" is 15. Careful: don't put a zero before a decimal number, it will be intepreted as an octal number! The ":echo" command always prints decimal numbers. Example: > :echo 0x7f 036 < 127 30 ~ A number is made negative with a minus sign. This also works for hexadecimal and octal numbers. A minus sign is also for substraction. Compare this with the previous example: > :echo 0x7f -036 < 97 ~ White space in an expression is ignored. However, it's recommended to use it for separating items, to make the expression easier to read. For example, to avoid the confusion with a negative number, put a space between the minus sign and the following number: > :echo 0x7f - 036