Project35.Configure vim

Project 35. Configure vim

"How do I make my vim settings stick, and how do I define my own features?"

This project takes a brief look at configuring vim. The topic is too large to cover in this book, so the project simply suggests some useful settings and shows you where to place them. It also describes how to set up a configuration directory. Project 32 introduces vim, and Projects 33 and 34 cover advanced vim features, as well as vim windows and buffers.

Learn More

Refer to Project 32 to learn more about search and replace, and the options that are available.

Official vim Information

The official home page for vim (called vim online) is at www.vim.org. You'll find lots of useful information, including a hyperlinked version of the vim help system, FAQs, tips including an RSS feed, and an online version of Steve Oualline's book about vim.

Create a Configuration File

Other vim projects have suggested settings that can be applied from the vim command line. To enable case-insensitive searching, for example, we used

:set ignorecase

To make these settings stick across vim sessions, we must write them to a configuration file. Your personal settings are written to a file named .vimrc in your home directory. Edit this file now (perhaps using vim ) and add some of the settings listed below. Put each setting on its own line. Blank lines are allowed anywhere, and comments are introduced by double quotes.

A sample .vimrc is available at the official home site for vim. See the sidebar "Official vim Information."

The following settings configure vim search, and search-and-replace functions. Refer to Project 32 for more details on these options.

Tip

Read about each setting in the vim help pages by typing

:help setting-name

To read all about all the settings, make a gallon of coffee and type

:help option-summary

" These settings configure searching " set ignorecase " make searching case insensitive set smartcase  " make searching case sensitive when the                " search term has one or more capitals set hlsearch   " highlight text matching the search term                " type :nohl to remove current highlights set incsearch  " search as the search term is being typed set matchpairs+=<:> " add angle brackets to the %                     " function bracket matching list

The settings in the next batch configure the way vim wraps text and how it treats tab characters. The comment text next to each sample setting explains what it does pretty clearly, but a couple of them bear some extra explanation: The nowrap (no wrap) setting turns off soft wrap. Soft wrapping is the default vim behavior of displaying long lines of text across multiple lines within a window, but without inserting hard line breaks. The wrapmargin setting, by contrast, tells vim to insert line-feed characters at the end of wrapped lines so that their line returns become permanent within a file. This feature should not be used when writing code.

" These settings configure auto-formatting features " set nowrap        " wrap long lines (on by default) set linebreak     " wrap long lines on one of these                   " characters: "space ^I!@*-+;:,./?" set wrapmargin=2  " insert linefeed to wrap text 2 chars                   " before right-hand side of window set expandtab     " expand Tab characters to spaces set softtabstop=3 " expand Tab characters as 3 spaces

The sample settings below switch on and tweak the look of the vim status bar, which is not usually displayed unless the Terminal screen is split into two or more vim windows.

" Switch on display of status line and tweak the settings " set laststatus=2  " always show the status line set ruler         " show the cursor position set showcmd       " display incomplete commands

We can tweak the vim command line, too.

" Tweak the setting of Vim's command line " set showmode      " show the current Vim mode set history=50    " keep 50 lines of command line history set report=0      " report # lines changed by each command

Shown below are just a few of the many vim settings designed to help programmers. Sometimes, it's easier to hide inner details when reading a complex piece of code, and the vim folding technique does so by collapsing (or folding) sections into single placeholder lines within the vim window.

The foldmethod setting is most often indent, meaning that code sections that reach a specified level of indentation are folded. The foldlevel setting specifies the level of indent at which text is folded. The shiftwidth setting specifies how many columns are equivalent to one level of indent. Typing zr and zm reduces and increases the amount of folding. In the sample below, folding would occur after 8 levels of indent or the equivalent 24 leading-space characters.

" Some settings that are useful when coding " set number        " display line numbers set showmatch     " after typing a bracket, briefly show                   " the matching bracket set autoindent    " automatically indent new lines set foldmethod=indent " fold by indent level set foldlevel=8  " initially fold levels beyond 8                   " changed by the zr and zm commands set shiftwidth=3  " this is the size of an indent and must                   " match the setting softtabstop above

Tip

To view the current state of a setting from within vim, type

:set setting-name?

That is, append the query (?) character to the end of the setting name.

The next settings turn on color display and syntax highlighting. Setting vim variable term overrides Terminal's native setting. When this is set to xterm, rather than xterm-color, vim cannot display in color. (This seems to be the case with X11's xterm.)

" Turn on color display and syntax highlighting " set term=xterm-color " incase Terminal is set incorrectly set t_Co=16 " enable 16 color display over 8 syntax enable " enable syntax coloring " here is a good point to load your own color scheme let colors_name = "cool" " enable cool color scheme

Finally, here are some miscellaneous settings.

" Miscellaneous settings " set autowrite    " autosave on commands such a :next set nocompatible " not vi compatible set backup       " write a backkeep a backup file set modeline     " Vim will check for setting embedded in                  " text file, see :help modeline set modelines=8  " # lines checked for embedded settings set vb t_vb=     " Switch off the annoying bell

Create Key Shortcuts

vim has a few features that can save you typing and make light work of repetitive tasks. These are

• Macros. Define up to 36 macros by assigning macro namesa to z or 0 to 9to a series of keystrokes. The keystroke sequences can be replayed at any time. Macros are covered in Project 33.

• Abbreviations. Define short sequences of characters that automatically expand into longer sequences when you type them.

• Key mappings. Assign sequences of keystrokes to a single key or sequence of keystrokes.

Note

When defining abbreviations and macros in vim, you must first type a colon to move onto vim's command line; if you write settings into a .vimrc configuration file, no colon prefix is necessary.

Abbreviations

You define an abbreviation as follows: Type ab and then the abbreviation, followed by the text to which the abbreviation should expand. For example:

ab PP Peachpit Press

From now on, each time you type PP, vim will replace it with Peachpit Press. Naturally, PP has to stand alone to be replaced, so APPLE won't mutate into APeachpit PressLE.

Tip

Use abbreviations for autocorrecting common typos, such as

ab teh the

Key Mappings

With vim, you can map a sequence of keystrokes to a given key, such as Function-2 (denoted by <F2>), or a few keystrokes, such as \h1. There's an important difference between abbreviations and key mappings. An abbreviation replaces text for text, whereas a key mapping replaces keystrokes with keystrokes. Therefore, a key mapping can comprise sequences of vim commands that insert text, delete text, move the cursor, or even perform a search-and-replace or global command.

Let's look at an example. Suppose that you often write HTML code and want a key mapping that encloses text between the HTML heading tags <h1> and </h1>. More specifically, you'd like to be able to place the vim cursor on the untagged heading line below and trigger your macro keystroke sequence \h1. . .

This is a Heading One Text...

. . . so that you finish with your cursor on the text line Text... and the heading tagged, like so.

<h1>This is Heading One</h1> Text...

To pull this off, we must first determine the keystrokes that will insert the tags at the start and end of the heading and then assign those keystrokes to \H1. When preparing any macro, we must also consider the mode vim will be in when the key mapping is applied. If a macro that needs the command line is to be run in insert mode, for example, its first recorded keystroke should be Escape. Fortunately, vim allows you to assign two mode-specific variants of a macro to the same keymap, so you can have identical keymap behavior in either mode.

Keymaps for vim normal mode are defined with command map, and their insert-mode counterparts are defined with map!. (Actually, we'll use noremap and noremap!variants that are most often the best ones to choose; type :help map for full details.)

Let's start by defining a key mapping for normal mode. We must insert at the start of the line (I) the text <h1> and then press Escape (denoted by typing literally <ESC>).

I<h1><ESC>

Next, move to the end of the line, using A, and add text </h1>. Then press <ESC>.

A</h1><ESC>

Finally, for convenience, we move down two lines (jj) to leave the cursor on the first line of text after the heading and move to the start of that line (^).

jj^

Putting this all together, and using noremap to define the normal-mode sequence, we have

noremap \h1 I<h1><ESC>A</h1><ESC>jj^

The version applied in insert mode is the same, plus an initial <ESC> and a final I, and is assigned with noremap! (with a pling at the end).

noremap! \h1 <ESC>I<h1><ESC>A</h1><ESC>jj^I

You may want to insert two linefeeds instead of moving the cursor down, which you can do with <CR><CR>.

vim Configuration Directories

Many default vim configurationssuch as those for file-type mapping, syntax coloring, key mappings, and autoindentationare defined in a global configuration directory. You may override global settings and add your own by setting up a local configuration directory. The next two sections discuss this topic very briefly, just to make you aware of the further potential of vim configuration.

Global

Explore this directory, which contains all the global vim configuration files: /usr/share/vim/vim62. (vim62 may be vimnn, where nn is the version of vim you have installed.)

Local

The key mappings we defined above are applicable only to HTML files, so we might want to define \h1 differently for other file typesand, of course, with vim we can. For vim to load custom keymap definitions for different file types, the definitions must be stored in special configuration files, or plugins, rather than in the file ~/.vimrc.

Create a directory called .vim in your home directory. Within this directory, you might create the following subdirectories.

$ ls -lR ~/.vim drwxr-xr-x 6 saruman saruman 264 Apr 16 16:36 colors drwxr-xr-x 4 saruman saruman 264 Oct 6 2003 ftplugin ~/.vim/colors: -rw-r--r-- 1 saruman saruman 3569 Dec 24 16:02 cool.vim -rw-r--r-- 1 saruman saruman 3206 Apr 19 2003 html.vim ~/.vim/ftplugin: drwxr-xr-x 5 saruman saruman 264 Jun 20 23:35 html drwxr-xr-x 3 saruman saruman 264 Oct 6 2003 php ~/.vim/ftplugin/html: -rw-r--r-- 1 saruman saruman 628 Jan 4 14:19 colors.vim -rw-r--r-- 1 saruman saruman 2521 Dec 19 2004 tags.vim ~/.vim/ftplugin/php: -rw-r--r-- 1 saruman saruman 874 Oct 6 2003 tags.vim

Within colors, you can place custom color schemes.

Within ftplugin, you can place plugins for different file types. Create a subdirectory for each file type you want to customize, and use the file type's extension as the name of the subdirectory. Here, we have subdirectories for HTML and PHP files.

Tip

Try the following vim help topics:

:help ftplugin :help syntax :help :color

Whenever vim loads a file of one of those types, it will execute all the .vim configuration files in the corresponding directory.

So we'll place the HTML-heading key mapping we defined earlier in a file called tags.vim (the file can have any name, as long as it ends with .vim), and place it in the HTML plugin directory.