The Golden Ratio

The .vimrc file is the configuration file of Vim. (For an introduction to Vim you can read my previous blog post about Vim). Since Vim is very customizable, it is important to have an easy way to keep your settings between each session. Re-entering all settings for each time you start Vim would be very cumbersome and not worth it in the end. This blog is a short introduction to how to create your own vim configuration file, as well as introducing you to some new functions of Vim.

At the end of my first blog about Vim I added a very short description of the .vimrc file, but there is much more to learn about the configuration file. During this blog post I’m going to cover how to set basic options, what abbreviations are, how to create and use functions, how to map keys and key combinations so that you can use your new functions or change settings on the fly. I won’t introduce many new options during the article. Reason for that is that which options you want or need is very individual and the amount of options available is enormous. But I’ve included an example .vimrc file at the end of the article where I’ve used options that I think most people will find helpful. To learn about other options you can either use the help file provided with Vim or Google for .vimrc.

My definition of an option and an ex command might differ a little bit from what you’ll find in other places. An ex command is the command that you type when you’re in the Command mode (when you’re typing text preceded by a : in the bottom left corner). Examples of ex commands are :%s/Pip/Peregrin/g(search and replace Pip with Peregrin) and :buffers(list current open buffers). An option is in this text used for an ex command with the following syntax: :set optionname[=value], where the =value is optional depending on the option. During the article I sometimes add the : in front of the ex commands and options, sometime I don’t, depending on what feels right in the context. Hopefully it won’t confuse you.

The amount of possible settings to configure in Vim is huge. Because of that I won’t go into detail about too many of them. Instead I’ll focus on the other aspects of the vimrc file; how to set it up with control statements, using functions etc. As I cover those I’ll use options I personally use in my configuration file. That way you’ll encounter quite a lot of different options in this blog, without dedicating specific space for them. For a quit list of the options I’ll cover you can look at the example .vimrc file supplied at the end of this blog.

Options

The most basic part of .vimrc file - short of writing comments - is setting options. You set an option by writing set optionname[=value], where the =value is optional depending on the option. To test an option before adding it to the .vimrc file you can enter Command mode and there type the option as you would in the .vimrc file. So if I want to test the set nu option (for line numbering) before adding it to the .vimrc file, I would enter Normal mode (by press <esc> to get there from any of the other modes) and type :set nu. The : in front is to enter Command mode, and the set nu is the option I’m testing. If the result is the one I want I’ll then add it to my .vimrc file as a new line. The same goes for all other commands added to the .vimrc file (except functions), prefix them with an : and you can test them before adding them to the .vimrc file.

Using If

During the ‘options setting stage’ the if statement is very useful. As you can see in the example .vimrc file provided at the bottom I’ve used it to enable folding (see Vim’s help file for more information on folding) if the current version is greater or equal to 600 (version 6.0). The syntax used for that is:

if version >= 600
    set foldenable
    set foldmethod=marker
endif

As you see the usage of the if statement is very simple. Vim checks if the version is greater than 6.0; if it is the commands between this line and the endif are executed, if not it’ll jump to the line bellow endif and continue there as if nothing had happened. The drawback is that you’ve got to know in which version the different features are available. An easier way to check for options of features is to use the has(...) option. This option is also used in the example file. The way it is used there is as follows:

if has("autocmd")
	... code ...
	... code ...
endif

The if statement checks if autocmd is available, and if it is it will execute the code snippets.

autocmd

The autocmd statement is used to execute a command each time a specified event occurs and the file in question matches a given path. The syntax for the command is autocmd {event} {path} {ex commands and options}. Both {event} and {path} are comma delimited strings with either the event or path to match. It is important not to enter any spaces in either of those strings, since if you do Vim will interpret that as if you moved to the next ’stage’. The {ex commands and options} is a listing of ex commands or options that should be run when both the event and path matches. Since this is the last part of the command you can use spaces freely here.

The most used events - which happens to be the same as the those in the example .vimrc filebellow - are:

BufRead

When starting to edit a new buffer

BufNewFile

When starting to edit a file that doesn’t exist

FileType

When the filetype option has been set

BufWritePost

After the buffer has been written to the file

When you know that you can look at the following line:

autocmd BufRead,BufNewFile *.java set expandtab

Rewritten into normal English it can be read in the following manner; “When a new file or buffer is created set expandtab if the filename matches *.java” (set exapandtab converts tab characters to spaces.) This is a very nice feature when you’re dealing with different coding and documentation specifications for different projects or languages. You only have to add one line to the .vimrc file for each project and it will automatically use the right tab conventions.

The Wonders of the Exclamation Mark

Two of the autocmd statements in the example .vimrc file uses a special prefix for their commands as you can see bellow.

autocmd BufWritePost   *.pl         !chmod +x %

The BufWritePost says that the commands are to be executed when the file has been saved, and the path part matches a Perl file. What then follows is !chmod +x %. The most important part of that statement is actually the exclamation mark. The exclamation mark send a specified piece of text to a given program. In this case the whole file (symbolized by the %) is sent through chmod +x, that is a *nix program that makes the file executable. This way of using that command is a little bit special, but very handy.

The usual way of using the ! is to write is as follows: {motion/range}!program. That way you can easily filter any part of your file through a program. An example of this usage is when you have got a couple of lines that you want sorted. Say that you for example have the following in you file:

Ted
Alexander
William
Hanne
Krista

If the text start at line 1 and ends at line 5 you could easily sort these alphabetically by typing :1,5!sort. This will send line 1 to line 5 through the sort program and place the output on line 1 to 5, thereby deleting your original content. You can also sort the lines if you first type !, then to the motion and then type sort. But that way of doing it won’t work in a script, since the whole purpose of the script is to automate the action - and if you have to do the motion it isn’t automated.

Using the ! and autocmd BufWritePost it is for example possible to make Vim auto commit changes to a svn repository. That way you can ensure that the last changes you do always gets committed. This can also be done the other way around; using autocmd BufRead to automatically update your local file when you open it.

Abbreviations

Abbreviations in Vim are words that when typed are replaced with something else. This is a useful feature to save you from typing the same words over and over again. It can also be used to correct common misspellings, for example typing teh instead of the. In Vim the abbreviation is changed as soon as you press a key after the word has been typed, but you cannot interrupt the typing - for example pressing <esc> and then re entering Insert mode - between two letters.

The ex command for creating abbreviations is ab <abbreviation> <target text>. If you want the abbreviation to only function when you’re in Insert mode you can add an i to the ab. The command would then be iab <abbreviation> <target text>. In the same manner you can change the abbreviation to only work in Command mode my adding a c. To create the abbreviation that changes teh to the you use ab teh the. The abbreviation cannot contain spaces, but the target text can. Another nice thing to note is that abbreviations aren’t recursive, so ab f foo won’t crash your computer.

To remove an abbreviation you use una <abbreviation>. As with the ab command you can add c or i to only effect to a single mode.

Keyboard Mapping

The ability to create your own keyboard short cuts, and to map these to all kinds of functionality is another great feature of Vim. The standard set of short cuts are great, but there are always more ways that it can be optimized to fit the specific user.

To create your own keyboard mappings you have to issue the ex command map. The syntax for it is map <key combination> <action>. The like abbreviation command you can append a prefix to specify in which modes the mapping should work. The most common possibilities here are nmap for only Normal mode, vmap for only Visual mode and imap for Insert mode. Note that you have to specify Insert mode for the mapping for work there, it isn’t covered by the normal map command. The <key combination> used for the mapping can use any key on the keyboard, even those already bound to commands. To avoid overriding any default Vim commands I usually start with a <ctrl> combination or a comma. The <F(1-12)> keys can also be used, but since they are so far away from the rest of the keyboard you should only use them for shortcuts that you rarely use. If you look at the example file at the end you’ll see that the only short cuts mapped to a function key is the toggle for search highlighting. All other short cuts are placed within easy reach of the fingers.

Similar to the abbreviations the key combination can’t contain any spaces, if you want to use space as one of the keys you write <space> in the key combination. To create a <ctrl> combination you write <c-key>, where key is the key you’ll press alongside <ctrl>. If you want to use an <alt> combination you replace the c with an m (for meta key), so they code becomes <m-key>. As you might have guessed the combination of <alt>+<ctrl>+key is written as <cm-key>. To require another character after the <ctrl/alt> combination you simply append the key, or character, name. So a sequence of <ctrl>+a followed by a k would be written as <c-a>k.

The ‘action’ that you map these key combinations to can be sequence of commands in Vim. You can create a mapping to move the cursor around, or to insert a certain text. As long as it is possible in Vim you can create a mapping for it. The syntax of the mapping is simply a listing of the keys that should be pressed. So a mapping that inserts ‘Hello World’ at the beginning of the current line could look something like map <c-h>hw IHello World<esc>. The first two words are the command for starting a mapping and the key combination required, which in this case is <ctrl>+h followed by an h and a w. After that comes the sequence to be entered, IHello World<esc>. If we take it apart we see that first I is pressed to enter Insert mode at the beginning of the current line. Hello World is then written and <esc> is pressed to return us to Normal mode.

As you see from the previous example it is possible to use special keys, like <esc> in the mappings action. Other special characters that are often used - aside from &lt;ctrl> and <alt> which we’ve already covered - are <cr> to represent enter and <bar> to represent the pipe character. The <cr> is used when you map ex commands or options, since after you’ve written them you execute them by pressing enter. So a mapping for saving the current file could look like map <c-s> :w<cr>. When creating mappings it is important to remember where you are in Vim, since characters have different meaning depending on if you’re in Normal mode or in Insert mode. Another important thing to know when working with mappings is that, unlike abbreviations, they are recursive. So it is possible to create mappings that loop ad infinitum.

Similar to options and abbreviations, mappings are added to the .vimrc file by simply creating a new line and putting the whole map command there.

Functions

Functions in Vim are defined similarly to how you would define them in any programming language. You start with Function[!] <function-name>(parameters), and end them with endfunction. The exclamation mark after Function is optional, if you add it the new function will override any other function with the same name. If you don’t have it and a function with the same name exists you’ll get an error message and the new function will be discarded. You should also note that function-name has to start with an upper case letter. The function body can consist of as many ex commands and options as you like.

function! Foo()
	echo "Foobar!" 
endfunction

The example function above is probably the simplest function available, that still does something. It only contains one command, echo "Foobar!". The echo command sends text to the bottom line of your ‘Vim screen’, same place that you type ex commands. In this case it will write Foobar! there.

The ex command for calling a function is either call <function> or echo <function>. The first variant calls the function and lets it execute before returning control to you. That is the simplest way to call a function. The second variant, using echo, lets the function execute, but before returning control it prints the function’s return value. This is only useful if the function returns a value. To make a function return a value you must terminate the function with the return <value> command. If you don’t specify a return value the function will return 0.

Arguments

The previous example can be useful for grouping and executing a bunch of ex commands, but without a way for the user to control the function’s behaviour at run time the uses are limited. Luckily we can pass arguments to the function and through them make the functions do exactly what we want.

function! Foo(txt)
	echo a:txt
endfunction

This little function takes an argument and then echoes it back to you. You access the arguments passed to the function by writing a:<argument-name>, the a: stands for argument. To send text as an argument you have to encapsulate the text inside quotes, doesn’t matter if it is double or single quotes. To pass a numerical value you just skip the quotes and write the number. If you want the previous function to print Foobar you use call Foo("Foobar") to call the function. It is possible to pass more than one argument to a function, as long as the arguments don’t have similar names. The arguments are separated by commas when you create and call the function, for example function! Foo(txt, txt2) and call Foo("hello", "world").

Text insertion

To insert text using a function there are two things you must do. First thing is to decide on which line you want to insert the text and the second is to put the text there.

To get what line the cursor is currently on you can use the function call line("."). The . passed to the function symbolize the current line. It is also possible to replace the . with a $ to get the last line in the current buffer. Now that you know how to figure out which line your on, we need to learn how to insert text relative to that line. That function looks as follows: setline(line_num, text). We can now expand our Foo function to put the txt argument into our document.

function! Foo(txt) 
    let l:myline = line(".") 
    call setline(l:myline, a:txt) 
endfunction

As with the previous function we call this one with :call Foo("text").

The second line in the function is let l:myline = line("."). The last part of it, line("."), returns the current line number as we noted earlier, but the first part of that line is new to us. The let command creates a variable and assigns a value to it, if the variable already exists its value is overridden. The variable name is in this case myline. In the function the variable name is prefixed with a l:. The prefix is used to decided the scope of the variable. The l: implies that the variable is restricted to the current function scope. The default scope of a variable is l: so in our case we could have written let myline = line(".") instead, but it is easier to keep track of everything when you add the prefixes.

On the third line we use our new variable to insert some text. The first command on this line is the call command, which we know is used to call upon a function. The function we’re calling is setline(l:myline, a:txt). As you can see this is a function that takes two arguments, first one is the line on which to set the text and the second argument is the text to set there. We are already familiar with the two arguments passed to the function, the first one is our l:myline variable that holds the current line number and the second one is a:txt which is the argument passed when we called the Foo function. A very important part thing to remember is that this function removes what is currently on the line before putting the new text there. That implies that the Foo function now replaces the current line with the text passed to the function. Changing the current line to Foobar the Great could then be accomplished with call Foo("Foobar the Great").

It is possible to add and subtract numbers from the first argument in the setline(...) function. So if you wanted the text to be inserted on the line bellow your the cursor you could change the third line to call setline(l:myline+1, a:txt). This is very useful for inserting large blocks of text. You could for example create a function that inserts a function heading bellow the current line. The FunHeading() function in the example does exactly this.

Execution time

An often used ex command in functions is the execute command. It takes an expression, evaluates it and then executes it. Take for example execute 'echo "h"'. The expression in this case is 'echo "h"'. Since this example doesn’t contain any special characters or variables it is passed along to the execute command without any change. The execute command then executes the command, which in this case echoes h. A thing to note here is that the h is encapsulated by double quotes, while the whole expression is encapsulated in single quotes. We do that because the outer pair of quotes are removed after the expression has been evaluated, so the inner quotes are needed to ensure that the h is treated as a string and not as a variable. We could have switched position of the double and single quotes in the example and it wouldn’t have made any difference. The important thing is that you don’t use the same type of quotes around strings as the one you used around the whole expression.

The good thing about the execute command is that multiple arguments can be concatenated into a single command. This can be used to create ex command that uses your arguments alongside preset strings. To concatenate arguments and/or strings you either separate them with a spaces or a dot. The two arguments are then joined together into one string with only a space separating them. For example; to concatenate "hello" and "world" you would write "hello"."world" and the result would be "hello world". To demonstrate this possibility we’ll rewrite our Foo function again.

function! Foo(txt)
	execute ":echo 'Hello'"."' World'"
	execute ":%s/".a:txt."/-foobar-/"
endfunction

In the second line (execute ":echo 'Hello'"."'World'") the expression that is to be evaluated is ":echo 'Hello'"."'World'". The first part - before the dot - is similar to our previous example, it will echo ‘Hello’ to the screen. The part including and following the dot is new to us. This part takes the string found to the right of the dot and concatenates it to the what is on the left, separating them with a space. We are then left with an expression that looks something like this: ":echo 'Hello World'". This is then sent to the execute command which prints ‘Hello World’ to the screen.

The next line in the example isn’t much harder to figure out. As you know from the first Vim blog a search and replace in Vim is written as :{range}s/search/replace/ and when {range} is set to % it should search the whole file. When you think of this and look at the third line you’ll recognize the search and replace pattern in ":%s/".a:txt."/-foobar-/". It looks like a command that will search through the whole file for a:txt (which we know is the argument passed with the function call) and replace it with -foobar-. That is absolutely correct! When you call the function with :call Foo("func") the concatenated string will look like this: ":%s/ func /-test-/". The spaces inside the search pattern doesn’t matter since Vim’s regexp engine ignores unescaped spaces.

An Example .vimrc

That is all for this time. Hopefully you learned something and got inspiration to learn more about Vim. I’ve included an example .vimrc file here to give you an idea of how to use much of what was covered.

"
" .vimrc file 
" created by Michael A. Plikk (blog.golden-ratio.net)
"
" Options
"
"""""""""""""""
 
colors elflord
 
set nocompatible  " enable vim specific commands
 
set noeb " disable error bells
set novb " don't blink the screen when there is an error
set backspace=indent,eol,start  " backspacing over indention, end-of-line 
                                            "and start-of-line
set cindent " c-style indenting
set nu  " set line numbering on
set noexpandtab  " keep the tab character, don't replace it with spaces
set fileformat=unix  " use the unix fileformat
set history=50 " keep 50 lines of command line history
set ruler " show the cursor position in the bottom right corner
set showcmd  " display incomplete commands
set digraph " enable digraphs, needed for special characters
set hidden " enable hidden files
set hlsearch " highlight last search 
set incsearch " show partial searches real-time
set magic " enable advanced regular expression in searches
set shiftwidth=4 " number of spaces used with (auto)indention
set tabstop=4 " tab size
set textwidth=78 " textwidth
 
syn on " automatic syntax hi lighting
 
set backupext=.bak  " Append `.bak' to backups
set backupdir=~/.backup,.,/tmp
set directory=.,~/.backup,/tmp
 
if version >= 600
    set foldenable
    set foldmethod=marker
endif
 
"
" Abbreviations
"
"""""""""""""""
iab _NAME Michael A. Plikk
iab _URL http://blog.golden-ratio.net
iab _DATE <C-R>=strftime("%A, %B %e %Y %I:%M:%S %p %Z")<CR>
 
"
" Keyboard remapping
"
"""""""""""""""
 
map &lt;F4&gt; :set hls!&lt;cr&gt;  toggle hi light search on/off
 
map &lt;c-k&gt; &lt;c-w&gt;k " go one window up
map &lt;c-j&gt; &lt;c-w&gt;j " go one window down
map &lt;c-h&gt; :bp&lt;cr&gt;  " go to previous buffer
map &lt;c-l&gt; :bn&lt;cr&gt; " go to next buffer
map &lt;m-k&gt; &lt;c-w&gt;k&lt;c-w&gt;_&lt;c-w&gt;&lt;bar&gt; " go one window up and maximize it
map &lt;m-j&gt; &lt;c-w&gt;j&lt;c-w&gt;_&lt;c-w&gt;&lt;bar&gt; " go one window down and maximize it
map &lt;m-h&gt; &lt;c-w&gt;h&lt;c-w&gt;_&lt;c-w&gt;&lt;bar&gt; " go one window left and maximize it
map &lt;m-l&gt; &lt;c-w&gt;l&lt;c-w&gt;_&lt;c-w&gt;&lt;bar&gt; " go one window right and maximize it
 
map &lt;c-s&gt; :w &lt;cr&gt; " save
 
map ,brack :call BracketRemove()&lt;cr&gt;
 
map ,edit :sp $HOME/.vimrc&lt;cr&gt;  " open .vimrc in a split window
map ,source :w&lt;cr&gt; :source $HOME/.vimrc&lt;cr&gt; " save and reload .vimrc
 
 
"
" Functions
"
"""""""""""""""
 
" Remove triple brackets used to shorten functions
function! BracketRemove()
    execute ":%s/^# {{{[0-9]*//g"
    execute ":%s/^# }}}[0-9]*//g"
endfunction
 
function! ConvertDos()
    execute ":%s/^M//g"
endfunction
 
function! FunHeading()
	let l:myline = line(".")
	call setline(l:myline, "####################################");
	call setline(l:myline+1, "#");
	call setline(l:myline+2, "#		function: &lt;function name&gt;");
	call setline(l:myline+3, "#		author: Michael A. Plikk");
	call setline(l:myline+4, "#");
	call setline(l:myline+5, "####################################");
endfunction
 
"
" Auto Commands
"
"""""""""""""""
 
if has("autocmd")
    autocmd BufRead,BufNewFile *.java set expandtab
 
    " Auto set text with for text files
    autocmd FileType text setlocal textwidth=79 | set wrap
 
    " Auto chmod +x on shell scripts
    autocmd BufWritePost   *.sh         !chmod +x %
    autocmd BufWritePost   *.pl         !chmod +x %
endif

Technorati Tags: Vim