Description

Increase the speed and amount of vim knowledge at your fingertips with precise searching of vim's items: keys (keybindings), options and commands. vimdb is aware of vim's default items, ones in your vimrc and ones in plugins. vimdb's plugin detection works only if you're using a pathogen-like setup i.e. each plugin has its own directory under ~/.vim/bundle/ (see Configuration below to change the directory). Tested with vim >= 7.2 on mac and windows. Works only on ruby 1.9.x.

Install

$ gem install vimdb

Usage

Basic examples searching different vim items:

# List keys with Ctrl
$ vimdb keys C-
+---------------+------+---------------------+------------------------------------------
| key           | mode | from                | desc                                    |
+---------------+------+---------------------+-----------------------------------------|
| 0 C-d         | i    | default             | delete all indent in the current line   |
| <C-End>       | i    | default             | cursor past end of fil                  |
| <C-End>       | n    | default             | 1  same as "G"                          |
| <C-Home>      | i    | default             | cursor to start of file                 |
| <C-Home>      | n    | default             | 1  same as "gg"                         |
| <C-Left>      | n    | default             | 1  same as "b"                          |
...
262 rows in set


# List options that contain word 'window' in any field
$ vimdb options window -a
+----------------+--------+----------------------------------------------------+
| name           | alias  | desc                                               |
+----------------+--------+----------------------------------------------------+
| autochdir      | acd    | change directory to the file in the current window |
| bufhidden      | bh     | what to do when buffer is no longer in window      |
| cedit          |        | key used to open the command-line window           |
| cmdwinheight   | cwh    | height of the command-line window                  |
| cscopequickfix | csqf   | use quickfix window for cscope results             |
| cursorbind     | crb    | move cursor in window as it moves in other windows |
| diff           |        | use diff mode for the current window               |
| equalalways    | ea     | windows are automatically made the same size       |
| guiheadroom    | ghr    | GUI: pixels room for window decorations            |
| helpheight     | hh     | minimum height of a new help window                |
| icon           |        | let Vim set the text of the window icon            |
...
30 rows in set

# Search for commands from pathogen plugin
$ vimdb commands pathogen -f=from
+----------+-------+---------------------+-----------------------------------------------------+
| name     | alias | from                | desc                                                |
+----------+-------+---------------------+-----------------------------------------------------+
| Helptags |       | pathogen.vim plugin | :call pathogen#helptags()                           |
| Ve       |       | pathogen.vim plugin | :execute s:find(<count>,'edit<bang>',<q-args>,0)    |
| Vedit    |       | pathogen.vim plugin | :execute s:find(<count>,'edit<bang>',<q-args>,0)    |
| Vopen    |       | pathogen.vim plugin | :execute s:find(<count>,'edit<bang>',<q-args>,1)    |
| Vpedit   |       | pathogen.vim plugin | :execute s:find(<count>,'pedit',<q-args>,<bang>1)   |
| Vread    |       | pathogen.vim plugin | :execute s:find(<count>,'read',<q-args>,<bang>1)    |
| Vsplit   |       | pathogen.vim plugin | :execute s:find(<count>,'split',<q-args>,<bang>1)   |
| Vtabedit |       | pathogen.vim plugin | :execute s:find(<count>,'tabedit',<q-args>,<bang>1) |
| Vvsplit  |       | pathogen.vim plugin | :execute s:find(<count>,'vsplit',<q-args>,<bang>1)  |
+----------+-------+---------------------+-----------------------------------------------------+
9 rows in set

# Info about how a vim item is made
$ vimdb info keys
Created using index.txt and :map

# For a list of all commands
$ vimdb

More Usage

As you can see from the last example, vimdb supports options for each command. For a command's listing of options use --help or -h:

$ vimdb keys --help
Usage: vimdb keys [QUERY]

Options:
  -a, --all          search all fields
  -f, --field        field to query
  -i, --ignore_case
  -m, --mode         search by mode, multiple modes are ORed
  -n, --not          return non-matching results
  -r, --regexp       query is a regexp
  -R, --reload       reloads items
  --reverse_sort
  -s, --sort         sort by field
  -t, --tab          print tab-delimited table

Description:
  List vim keys

As you can see, keys can be searched by keystroke, mode, description or from (default, user or plugin name). Some examples:

# List keys with Ctrl-A combo
$ vimdb keys C-A

# List keys with Esc key
$ vimdb keys E-

# List keys with Leader
$ vimdb keys L-

# List keys with no Leader - not of last search
$ vimdb keys L- -n

# List insert mode keys
$ vimdb keys -m=i

# List keys I've defined in vimrc
$ vimdb keys user -f=from

# List keys from my plugins
$ vimdb keys plugin -f=from

# List keys from snipmate plugin
$ vimdb keys snipmate -f=from

# List keys that contain completion in description
$ vimdb keys completion -f=desc

Advanced Usage

vimdb can be customized with your own commands thanks to its rc file and command engine, boson. For example, my rc file defines a command that detects conflicts between default keys and plugin keys:

$ vimdb conflict
+-------+------+---------------------+---------------------------------------------------------------------------------+
| key   | mode | from                | desc/action                                                                     |
+-------+------+---------------------+---------------------------------------------------------------------------------+
| C-w o | n    | default             | close all but current window (like |:only|)                                     |
| C-w o | n    | zoomwin plugin      | <Plug>ZoomWin                                                                   |
| *     | n    | default             | search forward for the Nth occurrence of the ident under the cursor             |
| *     | nos  | tcomment_vim plugin | :TCommentRight<CR>                                                              |
| *     | n    | default             | search forward for the Nth occurrence of the ident under the cursor             |
| *     | nos  | tcomment_vim plugin | :TComment<CR>                                                                   |
...

If you look at conflict's implementation, you see it's only about a dozen lines. Since vimdb stores vim items as array of hashes, you can use these within commands for whatever purpose.

To illustrate creating a command, let's create one that lists the first given number of vim commands. In your ~/.vimdbrc:

class Vimdb::Runner
  desc "Prints first X options"
  def first(num)
    # Set item type we're retrieving
    Vimdb.item('options')
    puts Vimdb.user.items.first(num.to_i).map {|e| e[:name] }
  end
end

To test drive it:

$ vimdb first 5
aleph
allowrevins
altkeymap
ambiwidth
antialias

Configuration

Configure vimdb with a ~/.vimdbrc (in ruby), which is loaded before every command request. For example, to configure where plugins are stored:

# plugins stored in ~/.vim/plugins
Vimdb.plugins_dir = 'plugins'

For a more thorough example, see my rc file.

Vim Mappings

Since vimdb runs on ruby 1.9.x, there's a good chance you don't have vim compiled against ruby 1.9.x. No worries, use rvm or rbenv to install a 1.9.x version. Then to invoke vimdb within vim, set up a key to pipe out to vimdb using rvm or rbenv:

map <Leader>v :!rbenv exec vimdb
" or for rvm
map <Leader>v :!rvm 1.9.3 vimdb

Key Modes

Vim's key modes are represented as single letters

• n: normal
• c: commandline
• i: insert
• o: operation
• v: visual
• s: select

If you're unfamiliar with all these modes read about them in vim with ':h :map-modes'.

The following modes from :map were altered to fit into the above modes:

• ! -> ci
• l -> ci
• x -> v
• v -> vs

How It Works

This gem creates a vimdb database, ~/.vimdb.pstore, by parsing your vim documentation and outputs of vim commands. When an item is first searched it is parsed. Subsequent searches are cached. To reload (and reparse) you database, pass a --reload option to most commands.

Motivation

Wanted to learn faster than :help would let me.

Credits

• mattn for windows support

Contributing

See here

Todo

• Add support for more vim items - variables, functions
• Considering user annotation for vim items