My Vimrc

bairui, y u no?

I've been asked before why my ~/.vimrc is not available online.

I guess, deep down, there are probably feelings of apprehension about releasing something so personal and close to one's heart; that insensitive malcontents might throw stones through the windows and graffiti the walls.

A bigger and more real concern is that of the endemic affliction known as Cargo Culting. Vim is like a martial art. Mastery comes from years of rigorous, dedicated practice, lots of trials and accidents and occasional brilliant successes, study at the feet of other masters and plain old Time at the coal-face. There is no short-cutting this process. You can speed it along with the right approach, but you can not just dump a master's vimrc file at $HOME and think you're playing with the big boys now. That will only lead to tear-stained keyboards and hosed code.

Heh... I'm distorting the truth only slightly here, but I was just told a funny story that allegorises this tragedy: A good friend and fellow vimmer had his Vim set up with :cursorcolumn=80 to remind him where to constrain his code lines. A colleague passing by gasped, "Oh no! Your monitor is broken!". Upon explaining that everything was ok, that the monitor was indeed working fine and that Ti... er, I mean, my friend wanted the line there, the enquirer left mollified and quietly envious of this awesome feature that his Ec, er, I mean, editor didn't have. A week later, my friend discovered his colleague's computer had a dark red line too; only, his was drawn on a transparent plastic strip sticky-taped to the monitor.

:-)

In fairness... the colleague was mocking my friend, so this is not really a story of Cargo Culting, but it shows the phenomenon well, I think. Someone sees something awesome in another person's setup and blindly copies it in the vain hopes it will bring them equal fortune too.

While not a Vim Master, I do have the occasional sharp implement that is best kept away from curious beginners. To that end, I am not just pushing my vimrc up for you to copy blindly. I give you here a snapshot in time. I have annotated it in the hope that it shows you why I chose a certain option or implemented a particular solution. It is my intention that you learn how to wield this cutting edge tool with ample guidance and clear models.

So much for the What and Why. Now a little bit about the How. An expert is not born expert. Years of training go into the growth of his skills, techniques, tools and knowledge. My vimrc has grown over the years in the same way, from humble beginnings through proud days of development and embarrassing times of foolishness all the while with unremitting hubris.

You can see examples of that growth in the snapshot below. In various places I note pieces that might eventually grow to the point of becoming their own plugin. When they do, they will be cut out of my vimrc and put into a standalone plugin of their own. Doing this helps keep the core vimrc down to a manageable size. It also allows me to share it more easily with others.

Finally, the process of cleaning up my vimrc for public release was quite a long and intellectually grueling one. It generated the philosophical challenge: what is my Vim configuration? By this I mean, it occurred to me that my vimrc was not the entirety of my Vim configuration. I have extracted and encapsulated within plugins many times over productive growths from my vimrc throughout the years. They serve me well still, sitting mostly quietly at the sides, doing their jobs unnoticeably well. To forget these pieces and not include them in my configuration would be disingenuous. They provide many of the commands that my muscle memory relies on within Vim today. They are my Vim configuration; certainly as much as my vimrc can claim to be, anyway.

My Vimrc

" ~/.vim/vimrc_common
" Barry Arthur

" My 'office' has several people using Vim who would like to have a pleasant
" configuration without needing a neckbeard to get it. Sharing all of my vimrc
" with them would not only give them unicorns and rainbows, but would also
" leave them with dangerous sharps and nasty unexpecteds. To solve this
" problem, the vimrc is split into three parts:
"
" * A common shared by all (this file)
" * A $USER pre for things that the common depends on (like mapleader)
" * A $USER post for things that the user would like to override

" Use Vim not vi
"----------------
set nocompatible


" Initialize Plugin Manager
"---------------------------
" https://github.com/Raimondi/vim-pathogen
" Raimondi's pathogen allows multiple bundle dirs and
" provides a command interface to interrogate, enable and
" disable plugins.

call pathogen#infect('bundle/shared', 'bundle/local')

" bundle/shared contains plugins used by all
" bundle/local is for personal plugins


" Filetype & Syntax Highlighting
"--------------------------------
filetype plugin indent on
syntax on


" User Pre File
"---------------
" For things like (:help mapleader)
" Note: use <leader>gf to jump to the file
source $HOME/.vim/vimrc_${USER}_pre


" Options
"---------
" Use :help 'option (including the ' character) to learn more about each one.

" Buffer (File) Options
set hidden                     " Edit multiple unsaved files at the same time
set confirm                    " Prompt to save unsaved changes when exiting
set viminfo='1000,f1,<500,:100,/100,h  " Keep various histories between edits

" Search Options
set hlsearch                   " Highlight searches. See below for more
set ignorecase                 " Do case insensitive matching
set smartcase                  "   except when using capital letters
set incsearch                  " Incremental search

" Insert (Edit) Options
set backspace=indent,eol,start " Better handling of backspace key
set autoindent                 " Sane indenting when filetype not recognised
set nostartofline              " Emulate typical editor navigation behaviour
set nopaste                    " Start in normal (non-paste) mode
set showmode                   " Necessary to show paste state in insert mode
set pastetoggle=<f11>          " Use <F11> to toggle between 'paste' and 'nopaste'

" Indentation Options
set shiftwidth=2               " Number of spaces for each indent level
set softtabstop=2              " Even when using <Tab>'s
set expandtab                  " When pressing <Tab>, replace with spaces

" Status / Command Line Options
set wildmenu                   " Better commandline completion
set wildmode=list:full         " Expand match on first Tab complete
set showcmd                    " Show (partial) command in status line
set laststatus=2               " Always show a status line
set cmdheight=2                " Prevent "Press Enter" message after most commands
set statusline=%f%m%r%h%w\ [%n:%{&ff}/%Y]%=[0x\%04.4B][%03v][%p%%\ line\ %l\ of\ %L]

" Interface Options
set number                     " Display line numbers at left of screen
set visualbell                 " Flash the screen instead of beeping on errors
set t_vb=                      " And then disable even the flashing
set mouse=a                    " Enable mouse usage (all modes) in terminals
set ttimeout ttimeoutlen=200   " Quickly time out on keycodes
set notimeout                  "   but never time out on mappings
set list                       " Show tabs and trailing whitespace
set listchars=tab:⇥\ ,trail:·  " with nicer looking chars
set shortmess=atI              " Limit Vim's "hit-enter" messages


" Key Maps, Functions, Commands and Abbreviations
"-------------------------------------------------

" General Editing
""""""""""""""""""

" Help terms can include characters typically not considered within keywords.
function! ExpandHelpWord()
  let iskeyword = &iskeyword
  set iskeyword=!-~,^),^*,^\|,^",192-255
  let word = expand('<cword>')
  let &iskeyword = iskeyword
  return word
endfunction

" F1 to show context sensitive help for keyword under cursor
" Deliberately left off the terminating <cr> to allow modification.
" Moves the cursor to the beginning of the term for contextual markup.
" (:help help-context)
nnoremap <F1> :help <c-r>=ExpandHelpWord()<cr><c-left>

" F9 to show VimL function list
nnoremap <silent> <F9> :help function-list<cr>

" Grep help files for a pattern
command! -nargs=* -complete=help HG helpgrep <args>


" Resize windows
nnoremap <leader>h :exe "resize " winheight(0) / 2<cr>
nnoremap <leader>H :exe "resize " winheight(0) * 2<cr>
nnoremap <leader>w :exe "vertical resize " winwidth(0) / 2<cr>
nnoremap <leader>W :exe "vertical resize " winwidth(0) * 2<cr>

" Move between windows
nnoremap <a-left>    <c-w>h
nnoremap <a-down>    <c-w>j
nnoremap <a-up>      <c-w>k
nnoremap <a-right>   <c-w>l


" Move up and down visually across wrapped lines
nnoremap <Down>  gj
nnoremap <Up>    gk

" Move left and right across whole (:help WORD)s
nnoremap <Left>  B
nnoremap <Right> W


" Execute current line
nnoremap <silent> <leader>E :exe getline('.')<cr>

" Toggle list mode
nnoremap <silent> <leader>L :set invlist list?<cr>

" Reformat paragraph
nnoremap <silent> Q gqap

" F2 to toggle spelling
nnoremap <F2> :set invspell spell?<cr>

" F3 to trigger snipmate
" Note: This map might change in the future; it's
" currently part of an extended <Tab> experiment.
let snips_trigger_key = '<F3>'

" F6 to Toggle the TagBar
nnoremap <silent> <F6> :TagbarToggle<cr>


" Diffing
"~~~~~~~~~
" Note: This is begging to be moved into a Diffing plugin

" View changes made to a buffer since it was last saved
" storing original line in global g:diffline because it's used by several
" different diff commands - do and dc
function! DiffOriginal()
  let g:diffline = line('.')
  vertical new
  set buftype=nofile
  " 0read prevents a blank line at the top of the buffer
  " ++edit retains current option values for read operation
  " # is the alternate buffer (:help :_#)
  0read ++edit #
  diffthis
  exe "normal! " . g:diffline . "G"
  wincmd p
  diffthis
  wincmd p
endfunction

" Demonstration of creating a command that calls a function.
command DiffOrig :call DiffOriginal()<cr>

" Demonstration of a map calling a command.
nnoremap <silent> <leader>do :DiffOrig<cr>

" Close a DiffOrig session
nnoremap <silent> <leader>dc :q<cr>:diffoff<cr>:exe "norm! ".g:diffline."G"<cr>


" Highlighting
"~~~~~~~~~~~~~~
" Note: These might move into the SearchParty plugin

" Temporarily clear highlighting
nnoremap <silent> <c-l> :nohlsearch<cr><c-l>

" Toggle search highlighting (:help set-inv  :help E518)
nnoremap <c-Bslash> :set invhlsearch hlsearch?<cr>

" F8 to highlight all occurrences of word under cursor
" Note: Needs a better key. <F8> seems arbitrary
nnoremap <silent> <F8> :let @/='\<'.expand('<cword>').'\>'<bar>set hlsearch<cr>


" Make
"~~~~~~
" Note: Again, a candidate for extraction into an external plugin

function! QuietMake()
  write
  silent! make
  copen
  if empty(len(filter(getqflist(), 'v:val["valid"]')))
    cclose
  else
    wincmd w
  endif
  redraw!
endfunction

" Demonstration of calling a function from a map
nnoremap <silent> <leader>ma :call QuietMake()<cr>


" Find-in-Files
"~~~~~~~~~~~~~~~
" (:help :abbrev :lvimgrep :lwindow)
cabbrev lvim
      \ lvimgrep /\<lt><c-r><c-w>\>/gj
      \ *<c-r>=(expand("%:e")=="" ? "" : ".".expand("%:e"))<cr>
      \ <bar> lwindow <c-left><c-left><c-left><right>


" Plugins
"---------

" Matchit - comes with Vim but needs to be enabled (:help matchit-activate)
runtime macros/matchit.vim

" Third-party plugins:

"" https://github.com/tpope/vim-surround.git
"" https://github.com/scrooloose/nerdcommenter.git
"" https://github.com/scrooloose/nerdtree.git
"" https://github.com/garbas/vim-snipmate.git
"" https://github.com/honza/snipmate-snippets
"" https://github.com/vim-scripts/Tagbar.git
"" https://github.com/vim-scripts/NumberToEnglish.git

" Home-grown plugins:

"" https://github.com/dahu/Insertlessly.git
"" https://github.com/dahu/Nexus.git
"" https://github.com/dahu/Firstly.git
"" https://github.com/dahu/Zzzomg.git
"" https://github.com/dahu/vim-mash.git
"" https://github.com/dahu/SearchParty.git
"" https://github.com/dahu/Vimple.git
"" https://github.com/Raimondi/vim-buffalo.git
"" https://github.com/Raimondi/vim-pathogen


" Auto Commands
"---------------
" (:help :autocmd)
if has("autocmd")
  augroup vimrc
    au!

    " Jump to last-known-position when editing files
    autocmd BufReadPost *
          \ if line("'\"") > 1 && line("'\"") <= line("$") |
          \   exe "normal! g'\"" |
          \ endif

    " Default omni completion based on syntax
    if exists("+omnifunc")
      autocmd Filetype *
            \ if &omnifunc == "" |
            \   setlocal omnifunc=syntaxcomplete#Complete |
            \ endif
    endif
  augroup END
endif


" GVim
"------
if has("gui_running")
  set t_vb=                    " t_vb gets reset when entering GUI mode
  set guifont=Terminus\ 14
endif


" User Post File
"----------------
" For overriding the common settings defined here
" Note: use <leader>gf to jump to the file
source $HOME/.vim/vimrc_${USER}_post

Resist Read Only Realities, Part I

Part I - The Beast Bespoke

One thing I frequently find limiting in Vim is the disturbingly all
too frequent read-only commands that display data in a pager-like dump
with the only options being: space, d, j, b, u, k and q for moving
down and up and quitting the pager. This is lame. Sometimes we want
to be able to interact with that information, or see a filtered subset
of it, or have at it with even more freedom and flexibility to do with
as we choose.

Take for example, the :scriptnames command that shows all of the
scripts Vim has loaded since the session started, in load order. We
most commonly use this list to check for the presence of a new plugin
we've installed, to confirm that it's loading correctly. Indeed, this
is one of the diagnostics #vim denizens will demand of you when
presenting with plugin failures.

If all you have is a small handful of scripts, then perusing the
output of :scriptnames manually in a dumb pager is tolerable, if not
enjoyable. If you have a lot of plugins then this quickly becomes
painful. Wouldn't it be nice to be able to filter your :scriptnames
list so that it only showed scripts matching the pattern you're
looking for? What we crave is something like:

:scriptnames /\cnerd/

to select only the loaded scripts matching the case-insensitive
pattern 'nerd' (presumably to catch one of either NERDCommenter or
NERDTree.)

That would be nice. That is what we desire. But we are left wanting.
In fact, we're left with the unsavoury message:

E488: Trailing characters

Are we doomed to a baleful life of blind bumbling through screenfuls
of awkwardly navigated, 1970's style non-interactive data dumps?

No. We don't have to suffer this injustice. We are vimmers. We have
recourse. We can solve this problem with Vim's :redir command, in
various ways, such as:

• :redir > somefile
• :redir => somevar
• :redir @{a-zA-Z*+"}>   (to a register)

The Standard Redir Recipe

Solving the :scriptnames problem above with the file redirection solution:

:redir >myscripts
:silent scriptnames
:redir END
:edit myscripts
:v/\cnerd/d

This works, and isn't too painful to do manually when you need it,
so long as you don't need it too often. The :scriptnames command is a
prime example of one you wouldn't need to call very often. Having to
choreograph the five line dance above once in a blue moon is no great
ordeal, provided you can easily remember the right steps in the right
order.

Is this as good as it gets?

Well, actually, no. This is just the first step, showing you the crux
of the problem and the simplest of Vim's built-in solutions. Coming up
next, I will show you how to take it to the next level with a splash
of split, filter, join love.

Vim Can Haz Math

I got asked today how I might tackle the problem of calculating the arithmetic difference between values in a series. Take for example this mythical data file:

date: 2012 01 01
weight: 90kg
date: 2012 02 01
weight: 87.5kg
date: 2012 03 01
weight: 85.4kg
date: 2012 04 01
weight: 83.2kg
date: 2012 05 01
weight: 80kg

With the desired outcome of:

date: 2012 01 01
weight: 90kg
date: 2012 02 01
weight: 87.5kg (-2.5)
date: 2012 03 01
weight: 85.4kg (-2.1)
date: 2012 04 01
weight: 83.2kg (-2.2)
date: 2012 05 01
weight: 80kg (-3.2)

This is what I used:

:g/weight:/ copy . | silent! ?weight:??? copy . | - join | s/// | s//-/ | s/kg//g | s/.*/\='('.string(eval(submatch(0))).')'/
:g/weight:/ join

Slow Motion Replay
If that makes perfect sense to you and you're even wondering why I was so verbose in some places, then I have nothing left to teach you here. Otherwise, let's break this down to show what's going on:

Note:

• Vim uses the | character as a command separator, like the ; in C.
• Vim's :ex mode has a notion of the current line which many commands use as their default source or target address.

1. :g// is Vim's global command. It finds all lines in the buffer matching the specified pattern, in this case: /weight:/. On each match, it sets the current line to the line of the match and runs the series of | separated commands given to it.

Note: Some of the internal commands within this sequence can alter the current line, affecting the subsequent command's notion of where the current line is.

2. copy . duplicates the given address range to below the current line. With no explicit address given then the implied source address is the current line. This effectively duplicates the weight: found by the :g// command below itself. It also sets the current line to the destination address, so the next command in our chain will implicitly operate on the duplicated line as its current line.

3. silent! is used in this pattern in case the user has :set nowrapscan (which would cause the ?weight:??? to fail on the first matching line in the file, prematurely terminating our :g// command. If the user has :set wrapscan enabled, then the last weight: in the file will be found here. Either way, cleaning up the first line is a manual exercise for our hapless user in this tutorial.

4. ?weight:? searches back from the current line to the prior match of weight:. Because our current line was reset by the copy command to be the duplicated line, then a single search backwards will merely find the line we copied from. That's not good enough. We want the next one back again from that one. However, the ?? command, when chained, sets the current line again, so a subsequent ?? immediately after will find the next prior weight: line.  When a search (either forward with // or backward with ??) is used without an explicit search term, Vim uses the prior search term implicitly, so ?? means search backwards for... weight: (because that's what we last searched for, in the ?weight:? command to start with).

Question for the attentive: Why did I give the explicit pattern ?weight:? in that command and not rely on the prior implicit search pattern?

5. Remember that copy . duplicates the given address range to below the current line. The given address in this case was explicitly provided by the search in #4, which points at the actual prior weight: . The current line is the duplicated weight line from step #2, so this command will copy the second prior weight line to below the duplicated weight line. Also remember that the copy command resets the current line to that of the destination address. It might be instructive to see what a sample of the file would look like if we halted our command here. That is, if we were to run the command:

:g/weight:/ copy . | silent! ?weight:??? copy .

We would get:


... 
date: 2012 02 01
weight: 87.5kg
weight: 87.5kg
weight: 90kg               <-- current line
date: 2012 03 01
...

That is assuming you have :set nowrapscan . However, if you have :set wrapscan , you will actually see:

... 
date: 2012 02 01
weight: 87.5kg
weight: 87.5kg
weight: 80kg               <-- current line
date: 2012 03 01

...

Note: That rogue 80kg comes from the fact that the first match of the :g// command is at the top of the file so the subsequent ?weight??? wrapped backwards around the file, finding the bottom-most entry instead — which is 80kg in our sample data file.

But we're not done, so let's continue on. Here's the whole :g// command again:

:g/weight:/ copy . | silent! ?weight:??? copy . | - join | s/// | s//-/ | s/kg//g | s/.*/\='('.string(eval(submatch(0))).')'/

Remember that our current line is as indicated in the samples above.

6. - join moves back a line (from the current line!) and joins the following line to the current line. The result of step #6 from the three weight: lines shown in step #5 is:

weight: 87.5kg
weight: 87.5kg weight: 90kg     <-- current line

It's really instructive for you to run this partial command up to this point yourself to see the goblins I'm ignoring by deliberately choosing the second weight: match within the file. It's only a white lie that will all be cleared up later anyway, so I don't feel too bad about it.

The remaining 4 commands in the chain are substitutions which strip unwanted non-numeric pieces from the line, shape it into an arithmetic subtraction expression and evaluate it to produce the arithmetic difference between the two numbers. The following lines show the result of each command in turn applied to the result of step #6.

the s/// results in:

 87.5kg weight: 90kg

the s//-/ results in:

 87.5kg - 90kg

the s/kg//g results in:

 87.5 - 90

and, finally, the s/.*/\='('.string(eval(submatch(0))).')'/ results in:

(-2.5)

At this stage, the file looks like this:

date: 2012 01 01
weight: 90kg
weight: 90kg
date: 2012 02 01
weight: 87.5kg
(-2.5)
date: 2012 03 01
weight: 85.4kg
(-2.1)
date: 2012 04 01
weight: 83.2kg
(-2.2)
date: 2012 05 01
weight: 80kg
(-3.2)

We want the differences at the end of the preceding weight: lines, so we'll use another :g// command for that:

:g/weight:/ join

Which leaves us almost done. The only bugbear remaining is the duplicated first weight in the file:

weight: 90kg weight: 90kg

Clean that up manually.

Reflection

I could have approached this in a number of different ways, but to my mind, this seemed to be the quickest and easiest approach. Other approaches might include using a macro instead of a global command, or writing a full-blown VimL script.

I tend to build these things up piecemeal, testing as I go. I follow the same methodology when constructing SQL commands. Run a partial to prove to yourself that it's good so far. Press the u key to undo and add your next chunk. Repeat until you're done.



Writing up this article to explain the solution took twenty times longer than scratching the solution out for the requester in the first place.

Oh, the answer to my earlier question? Did you figure it out? The explicit pattern given in s/kg//g forces me to be explicit again at the start of the chained commands within the :g// command.