Chris Zingel

Vim Plugins using Ruby

July 25, 2012

Image 2

If you love Ruby and Vim then the next logical step is to combine them together and write Vim plugins using Ruby.

This is surprisingly easy though there are some limitation that you should be aware of but I will get to those below.

The exercise

I have taken a Vim script, that does a google search on a selected word, and converted it to use Ruby instead.

The Ruby plugin use the Unix command open to display the file using in its default application; the browser in our case for html.

" online documentation search
" This opens the webbrowser with at the appropriate place
function! OnlineDoc()
if &ft =~ "ruby"
let s:urlTemplate = "http://railsapi.com/doc/rails-v2.3.8_ruby-v1.8/?q=%"
else
return
endif
let s:wordUnderCursor = expand("<cword>")
let s:url = substitute(s:urlTemplate, "%", s:wordUnderCursor, "g")
let s:cmd = "!open \"" . s:url . "\""
execute s:cmd
endfunction

map <silent> <leader>d :call OnlineDoc()<CR>

For more information check out the original Vim script http://vim.wikia.com/wiki/Online_documentation_for_word_under_cursor

The hooks

There are a number of constants, objects or methods exposed by Vim that Ruby can use

Editor concept Ruby Python
eval VIM::evaluate vim.eval
command VIM::command vim.command
option VIM::set_option –
output VIM::message sys.stdout
buffer VIM::Buffer vim.buffers
window VIM::Window vim.windows
current buffer $curbuf vim.current.buffer
current window $curwin vim.current.window
range – vim.current.range

Page source: Stephen Bach post

Get the simplest thing working - "Hello world"

The first step is to make a “Hello World” application; making the simplest application using Ruby and Vim. This provides a starting point to dive into the code and explore how Ruby works with Vim - it’s easier to learn by doing.

To produce a simple text message in Vim using Ruby enter the following into the status bar:ruby print "hello world". This prints out the "hello world" texts to the status bar.

Let's break this down:

Command Description
Ruby executes the following text as Ruby script
print print method displays the message in the status bar (how cool is that)

Let's see what else we can determine about from our min-irb environment. Try typing the following in your status bar

Type in status bar Result
:ruby print 2+4 6
:ruby print self.class Object
:ruby print self.methods.sort.join(" ") => == === =~ __id__ __send__ class clone ... etc

The Print method allows us to explore the object and find Ruby methods that Vim provides.

In our tutorial, I am interested in knowing the following:

  • What is the file type that is currently active?
  • What is the word the cursor is currently on?

Determining the filetype and the active word

Using Vim's Vim::evaluate we are able to evaluate Vim commands and get access to the returned value which can then be used by Ruby. To see the filetype and active word using Vim, type the following commands.

Type in status bar Result
:echo expand('') => current word under the cursor
:echo &ft => current file's filetype

Important to note: These are Vim commands echo displays the return results in the status bar. For us to use Ruby, these Vim commands will need to be wrapped in the Ruby method VIM::evaluate

Type in status bar Result
VIM::evaluate("expand('')") => the current word under the cursor
VIM::evaluate("&ft") => the current file's fitetype

We now have all of the parts that we need to build our Vim macro.

Resources