Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Updates to the readme files.

  • Loading branch information...
commit 4d394f566d8b3d56ed36d7b844d1dbaabc38da69 1 parent 78c929f
@nelstrom authored
Showing with 76 additions and 2 deletions.
  1. +67 −2 README.md
  2. +9 −0 readme.vim.org
View
69 README.md
@@ -1,8 +1,73 @@
A custom text object for selecting ruby blocks.
-Depends on Kana's [textobj-user plugin][u].
+Depends on Kana's [textobj-user plugin][u]. Test suite requires [vspec][] (also by Kana).
-Test suite requires [vspec][] (also by Kana).
+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`
+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][u].
+
+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
+===========
+
+Specs are currently broken. :-/
Running the specs
-----------------
View
9 readme.vim.org
@@ -69,4 +69,13 @@ selection inwards by repeating `ir`.
First of all, ensure that you have installed vimscript #2100, without which
this plugin will not work.
+This plugin is distributed as a vimball, so to install it you just need to
+open the file with Vim and run the command:
+ :source %
+
+If you prefer to manage your plugins using pathogen (vimscript #2332), then
+you might prefer to checkout the latest version directly from github:
+
+* https://github.com/nelstrom/vim-textobj-rubyblock
+* https://github.com/kana/vim-textobj-user
Please sign in to comment.
Something went wrong with that request. Please try again.