NOTE: The latest version of these runtime files for Vim can be found packaged together as part of the the [Vim-Ruby Configuration Files project]
If you install Vim 7.x, the following Ruby support is enabled out of the box:
These files are maintained by MarkGuzman, TimHammerquist, DougKearns, GavinSinclair, TimPope? and NikolaiWeibull?
The purpose of this article is to describe what these features are, how they work, and how you can add other Ruby features. The target readership is those who use Ruby and Vim, but are not sure how to get the most out of the combination.
When you install Vim 7.0 (please don't use 6.x if you can help it!), the following important files are created ($VIMRUNTIME is the directory where the Vim runtime files are installed, like /usr/share/vim/vim70 or C:\Program Files\vim\vim70):
Since Vim 6.x, a lot of configuration and extensions have been placed in plugins. For instance, from VimOnline you can download plugins for a calendar or tetris. These are global plugins. The files we are concerned with are filetype-specific plugins.
The notion of filetype is central to Vim. When you load a file, Vim decides (based on either the filename extension or the file contents) the type of file you are editing. It then loads the specific runtime files for that filetype, in order to highlight it, indent it, and apply whatever other settings are deemed appropriate for files of that type.
Files with either a filename extension of .rb or a ruby shebang line (#!/usr/bin/ruby) will be set to filetype "ruby" and files with a filename extension of .rhtml will be set to filetype "eruby".
The filetype plugin files (ftplugin/*) are a place for miscellaneous configuration when editing Ruby and eRuby code: mappings, options, matchit configuration etc.
See :help matchit-activate for an explanation of how to enable the matchit global plugin. There is also a summary at the end of the ftplugin/ruby.vim file.
The syntax files contain instructions for Vim to highlight Ruby and eRuby code.
See :help ft-ruby-syntax for more details, including configuration options.
The indent files contain instructions for Vim to automatically indent Ruby and eRuby code.
The compiler plugins contain instructions which allow Vim to run the specified source file with an appropriate executable, parse any errors, and jump to the corresponding error location if required.
TODO: explain how to use these plugins
The omni completion function (autoload/rubycomplete.vim) file offers context sensitive (IntelliSense-like) completion similar to that available in irb.
NOTE: This functionality is new for Vim 7 and requires a version of Vim compiled with the Ruby interface - see :help ruby
To activate the completion menu type CTRL-XCTRL-O while in insert mode.
See :help ft-ruby-omni and :help i_CTRL-X_CTRL-O for more details.
While these files are included as part of the standard Vim distribution they tend to be updated more frequently than Vim itself. The latest can always be installed via RubyGems
# gem install vim-ruby --remote # vim-ruby-install.rb
or alternatively by downloading the appropriate [archive file]
Not necessarily - it's possible to [install rubygems in a user directory] - DougKearns
Unfortunately, although Vim has all this power, it is not enabled by default, primarily for "backward compatibility", I suppose. So make sure these lines are contained within your $HOME/.vimrc file:
set nocompatible " We're running Vim, not Vi! syntax on " Enable syntax highlighting filetype on " Enable filetype detection filetype indent on " Enable filetype-specific indenting filetype plugin on " Enable filetype-specific plugins
You should verify that your installation of vim-ruby is correct.
A simple way to do this in Vim 7, which will test that the syntax, filetype, indent and omni completion scripts are working properly, is to:
1.upto(5) do |i|
puts "#{i}. Infinity, the star that would not die"
end
The fragment should be highlighted and automatically indented as you type.
puts "#{i}. Infinity, the star that would not die".<CTRL-X><CTRL-O>
A list of string methods should be offered in a pop-up window. You can navigate this list with CTRL-N and CTRL-P and use CTRL-Y to accept a match.
NOTE: this step assumes you have Vim compiled with the Ruby interface (the output of :help version should include +ruby)
You can complement the system-wide settings with plugins placed within your home directory.
Inside the directories $HOME/.vim and $HOME/.vim/after (Unix), or $HOME/vimfiles and $HOME/vimfiles/after (Windows), exists the same directory structure as found in $VIMRUNTIME: in particular, the subdirectories ftplugin, indent, and syntax. If you put a file ruby.vim in any of these directories, you can tailor the way Vim treats Ruby files to your own needs. Files placed in the $HOME/.vim/after directory hierarchy can be used to override or add to the default settings in $VIMRUNTIME and files placed in the $HOME/.vim will replace the default settings. See :help runtimepath for more details.
I see no need to tamper with syntax highlighting or indenting, but being able to have Vim load up a special configuration file whenever a Ruby file is loaded is a great benefit. In fact, it can load more than one file. Here are the three important files that Vim loads whenever I edit a Ruby program:
You can see the pattern there. When the filetype is "ruby", Vim will load any files like those above.
In my directory, ruby.vim sets textwidth, softtabstop, and shiftwidth. That's it. (These are inappropriate for the system-wide ftplugin, because they reflect user preferences.)
ruby_structure contains a set of insert-mode mappings that make editing Ruby code much easier. My favourite one is the following:
imap <S-CR> <CR><CR>end<Esc>-cc
This enables the following shortcut. Say I'm writing an if-statement. Having typed:
if name == "John"[<--cursor]I can hit Shift-Enter and will get:
if name == "John" [<--cursor] end
This saves typing and enables me to keep the program balanced. Of course it applies to def, do, class, while, unless as well, and probably others.
I will provide all the details of my personal Vim/Ruby configuration in an appendix in the near future. (Well, that hasn't happened because I haven't actually written any significant Ruby code for a while.)
Maybe it will be useful to adopt the 2 spaces indend Ruby rule. In case use this
set expandtab
set tabstop=2 shiftwidth=2 softtabstop=2
set autoindent
The following extension works with braces, too. Having typed:
ary.map { |elem|[<--cursor]
I can hit Shift-Enter and will get:
ary.map { |elem|
[<--cursor]
}
Here's the code:
if !exists( "*EndToken" )
function EndToken()
let current_line = getline( '.' )
let braces_at_end = '{\s*\(|\(,\|\s\|\w\)*|\s*\)\?$'
if match( current_line, braces_at_end ) >= 0
return '}'
else
return 'end'
endif
endfunction
endif
imap <S-CR> <ESC>:execute 'normal o' . EndToken()<CR>O
-- PitCapitain?
<S-CR> didn't work for me, so I hacked this function to "do the right thing" (tm) when you press return. http://pmade.com/articles/2006/06/02/vim_mapping_for_ruby/
In addition to above, I have found this quite helpful:
imap <<- <<-QUOTE<CR><Tab><CR>QUOTE<Esc>-A
Get the latest released vim-ruby files from [Vim-Ruby Configuration Files project]
Created: 23 Oct 2002 Last Updated: 12 Apr 2006 (DougKearns)
Some questions Ruby Vimmers may be able to answer (put here as they may help others)[should these move to a /discuss page, or would that make editing this page more painful?]:
Is there a way to debug ruby code running inside vim (like printing the backtrace, etc) ?
With matchit you can jump to the balancing word def...end, if...else...end, but is there a way to jump to the enclosing syntactical structure, such as the def...end, or from def...end to the enclosing class...end structure? Can this be done without creating maps (which are harder to look up/remember and in vim there's less namespace for them than in vi)?
There's no way I know of to achieve this. It could be done imperfectly with search patterns.
Is there a way to jump to a method of a given class in the file, for example if there are many similar named methods in different classes in the said file? I think this is equivalent to asking if there is tags support for ruby, but I've not done much with tags.
Exuberant ctags does support Ruby (see bottom of page for more), but I doubt it would be able to resolve names in the face of many options. Good for basic navigation, though, and Vim's support for ctags is excellent.
[Gnu Global] [Irish mirror] may help with this, though it doesn't support Ruby at the time of writing (04-APR-2003). It does support vim though.
Exuberant ctags out of the box doesn't do a number of useful things:
- It doesn't deal with:
module A::B
- It doesn't tag (at least some of) the "operator" methods like '=='
- It doesn't support qualified tags, --type=+
Given that ruby objects tend to have the same methods in many, many classes, this is a killer, which #to_s did you want to look at? :-)
- It doesn't know initialise is really "new" (usually).
- It doesn't output multiple tags for methods with same indent level and same name in the same file:
class First def to_s end end class Second def to_s end end
This will generate only a single tag for #to_s with a search pattern of "/^ def to_s/", which will find the first, only, AFAICT.
- It doesn't output tags for constants or attributes.
See the Exuberant ctags mailing list, where Elliott Hughes (who wrote this) posted a [patch] for this. His editor, [Edit], uses Exuberant ctags to show a tree of classes and methods where what you're editing is highlighted, and you can click elsewhere to jump to that method, so he needed better Ruby support.
It's not perfect (it doesn't use the real Ruby yacc parser), but it's pretty good.
Why try to build a ruby parser in C if it's a) hard, and b) its already been done.
OK, what parses ruby code and knows the line numbers, and the full names of all the classes? Rdoc!
Not only that, it knows constants and attributes!
So, I'm trying to hack rdoc to give it a 'tags' output format generator.
Will report on results soon. One thing is obvious so far, exhuberant ctags is lightning fast.. and rdoc is anything but. I can live with that to get qualified tags, though. (You don't need to; see above.)
- Sam Roberts