A custom text object for selecting ruby blocks.
VimL Visual Basic Ruby
Permalink
Failed to load latest commit information.
doc Update docs with matchit.vim requirement. Dec 29, 2010
plugin/textobj Remove NeoBundle check Jan 22, 2014
t Set up `rake test` runner and use VimFlavor Nov 15, 2013
.gitignore Set up `rake test` runner and use VimFlavor Nov 15, 2013
Gemfile
Gemfile.lock Set up `rake test` runner and use VimFlavor Nov 15, 2013
README.md
Rakefile Set up `rake test` runner and use VimFlavor Nov 15, 2013
VimFlavor Set up `rake test` runner and use VimFlavor Nov 15, 2013
addon-info.json add addon-info.json so that VAM automatically activates textobj-user Nov 21, 2012
readme.vim.org Update READMEs with additional dependency info. Jan 26, 2011
textobj-rubyblock.vba Regenerate vimball for 0.0.2 release. Dec 29, 2010
todo.otl Create alternative readme for vim.org. Dec 27, 2010
vimballer Generate a vimball. Dec 27, 2010

README.md

A custom text object for selecting ruby blocks.

Flattr this

Depends on Kana's textobj-user plugin. Test suite requires vspec (also by Kana).

Also requires that the matchit.vim plugin is enabled. Ensure that the following line is included somewhere in your vimrc file:

runtime macros/matchit.vim

It is also essential that you enable filetype plugins, and disable Vi compatible mode. Placing these lines in your vimrc file will do this:

set nocompatible
if has("autocmd")
  filetype indent plugin on
endif

Usage

When textobj-rubyblock is installed you will gain two new text objects, which are triggered by ar and ir respectively. These follow Vim convention, so that ar selects all of a ruby block, and ir selects the inner portion of a rubyblock.

In ruby, a block is always closed with the end keyword. Ruby blocks may be opened using one of several keywords, including module, class, def, if, unless and do. This example demonstrates a few of these:

module Foo
  class Bar
    def baz
      [1,2,3].each do |i|
        i + 1
      end
    end
  end
end

Suppose your cursor was positioned on the word def. Typing var would enable visual mode selecting all of the method definition. Your selection would comprise the following lines:

def baz
  [1,2,3].each do |i|
    i + 1
  end
end

Whereas if you typed vir, you would select everything inside of the method definition, which looks like this:

[1,2,3].each do |i|
  i + 1
end

Note that the ar and ir text objects always enable visual line mode, even if you were in visual character or block mode before you triggered the rubyblock text object.

Note too that the ar and ir text objects always position your cursor on the end keyword. If you want to move to the top of the selection, you can do so with the o key.

Limitations

Some text objects in Vim respond to a count. For example, the a{ text object will select all of the current {} delimited block, but if you prefix it with the number 2 (e.g. v2i{) then it will select all of the block that contains the current block. The rubyblock text object does not respond in this way if you prefix a count. This is due to a limitation in the textobj-user plugin.

However, you can achieve a similar effect by repeating the rubyblock text-object manually. So if you press var to select the current ruby block, you can expand your selection outwards by repeating ar, or contract your selection inwards by repeating ir.

Development

Running the specs

Set up the testing environment by running this command from the project root:

bundle install

Then you can run the tests with rake:

bundle exec rake test

Generating a vimball

To distribute the script on vim.org wrap it up as a vimball by following these steps:

  • open the file vimballer in Vim
  • set the variable g:vimball_home to the development directory of this plugin (e.g. run: :let g:vimball_home='~/dotfiles/vim/bundle/textobj-rubyblock')
  • visually select all lines in vimballer file
  • run '<,'>MkVimball! textobj-rubyblock.vba

That should create a file called textobj-rubyblock.vba which you can upload to vim.org.

Credits

This plugin was built by Drew Neil, but the real credit goes to Kana, whose textobj-user plugin provides a framework for building custom text objects. I couldn't have created the rubyblock plugin without building on top of his hard work, so I'd like to say a big thanks to Kana.

License

Copyright (c) Drew Neil. Distributed under the same terms as Vim itself. See :help license.