documentation

Optional Plugins

In addition to the standard Vrapper plugin, we have a couple optional plugins that you can install to further enhance Vrapper's features. These plugins either have extra dependencies which everyone might not have installed, or they provide behaviors which aren't found in Vim.

Split Editor Plugin

The Split Editor Plugin provides commands for splitting editors vertically or horizontally and managing those splits. This is a standard Vim feature so it should be included in the core Vrapper plugin but our implementation utilizes the Eclipse 4 API. Rather than forcing all of our users to upgrade to Eclipse 4.x we are providing these features in an optional plugin so the core Vrapper plugin can continue to function on Eclipse 3.x.

The Split Editor Plugin supports the following commands:

:split [filename] <C-W><C-S> <C-W>s <C-W>S Create Horizontal Split :vsplit [filename] <C-W><C-V> <C-W>v Create Vertical Split :wincmd w <C-W><C-W> <C-W>w Go to other split :wincmd o <C-W><C-O> <C-W>o Close other splits :wincmd! H <C-W>ch <C-W>c<LEFT> Clone current split left :wincmd! L <C-W>cl <C-W>c<RIGHT> Clone current split right :wincmd! J <C-W>cj <C-W>c<DOWN> Clone current split down :wincmd! K <C-W>ck <C-W>c<UP> Clone current split up

:wincmd h <C-W><C-H> <C-W>h <C-W><LEFT> Move cursor to left split :wincmd l <C-W><C-L> <C-W>l <C-W><RIGHT> Move cursor to right split :wincmd j <C-W><C-J> <C-W>j <C-W><DOWN> Move cursor to split below :wincmd k <C-W><C-K> <C-W>k <C-W><UP> Move cursor to split above :wincmd H <C-W>H Move current split left :wincmd L <C-W>L Move current split right :wincmd J <C-W>J Move current split down :wincmd K <C-W>K Move current split up

Eclipse style tab switching

By default gt and gT commands will switch between all open editors regardless of window splits. The plugin provides additional mappings to switch tabs only within the currently active split:

:wincmd n <C-W>gt Switch to the next tab within the current split :wincmd p <C-W>gT Switch to the previous tab within the current split

You can change the default behaviour of gt and gT using the following remapping:

    nnoremap gt <C-W>gt
    nnoremap gT <C-W>gT

Programming Language Plugins

CDT, JDT, and PyDev Plugins

The CDT, JDT, and PyDev plugins access Eclipse features found only in the CDT package (C++ Development Tools) the JDT package (Java Development Tools), or PyDev package (Python Development). If you do any C++ development in Eclipse, chances are you already have CDT installed. Likewise with JDT for Java development. The Vrapper CDT plugin has a dependency on the CDT package, the Vrapper JDT plugin has a dependency on the JDT package, and the Vrapper PyDev plugin has a dependency on the PyDev package.

Each of these plugins provide the following commands:

gcc	comment/uncomment current line
gc<text object>	comment/uncomment text object
==	auto-indent current line (not applicable for PyDev)
=<text object>	auto-indent text object (not applicable for PyDev)
Ctrl+] gd gD	go to declaration of object under cursor
gR	rename element
:format	call underlying language's source code formatter

In addition to this, the JDT plugin also provides these commands:

gr	activate Eclipse's 'refactor' menu
gm	activate Eclipse's 'source' menu

We are able to define a mapping for any Eclipse operation within the org.eclipse.cdt.ui.edit.* or org.eclipse.jdt.ui.edit.text.java.* Eclipse namespaces. If there are any commands you'd like us to support, just file an Issue on our GitHub project.

Clang-Format Plugin

This plugin formats your C/C++/Obj-C code with specific coding style using LLVM clang-format tool (http://clang.llvm.org/docs/ClangFormat.html). You must have the clang-format command in your $PATH for the plugin to work.

The Clang-Format Plugin provides commands to invoke clang-format on a region of text and configure default formatting style options:

:clang-format [<style>]

With no region specified formats entire editor content using either default or the style given as the argument to the command. The command accepts any range specification including visual ('<,'>). The style can be anything that is acceptable as the -style command line argument to clang-format, including file:

                Coding style, currently supports:
                LLVM, Google, Chromium, Mozilla, WebKit.
                Use -style=file to load style configuration from
                .clang-format file located in one of the parent
                directories of the source file (or current
                directory for stdin).
                Use -style="{key: value, ...}" to set specific
                parameters, e.g.:
                -style="{BasedOnStyle: llvm, IndentWidth: 8}"
            

:clang-format-default-style <style>

Sets the style to be used for all editors when no style is given to clang-format.

:clang-format-style <style>

Sets the style to be used for this editor only when no style is given to clang-format.

Vimscript Ports

Improved Paragraph Motion (ipmotion.vim) Plugin

Ipmotion.vim is a vim plugin defined here:
http://www.vim.org/scripts/script.php?script_id=3952
This script modifies the behavior of { and } to be non-Vim compliant but more sensible. Basically, a line with only whitespace is considered a paragraph boundary rather than requiring lines to be completely empty. The script allows for any arbitrary regex to be used in determining paragraph boundaries; our port of this script does not currently include that behavior.

Argument Text Object (argtextobj.vim) Plugin

Argtextobj.vim is a vim plugin defined here:
http://www.vim.org/scripts/script.php?script_id=2699
This script defines a text object a (argument) to easily modify arguments within a method declaration.

Line Text Object (textobj-line.vim) Plugin

textobj-line.vim is a vim plugin defined here:
http://www.vim.org/scripts/script.php?script_id=3886
This script defines a text object l (line) to select everything within a line (minus the newline) or everything within the line without any trailing or starting whitespace.

Method Text Object (methodtextobj.vim) Plugin

Methodtextobj is a plugin based loosely on:
http://www.vim.org/scripts/script.php?script_id=2619
This script defines a text object f (function) to easily change and delete function contents. It is defined as the 2nd-level of matching { and } in a file (where a class definition would be the 1st-level). Thus it is handy for Java and C++ source files or similarly formatted code.

Indent Text Object (vim-indent-object.vim) Plugin

vim-indent-object.vim is a vim plugin defined here:
http://www.vim.org/scripts/script.php?script_id=3037
This script defines text objects i and I (indent) to easily change and delete indentation blocks of code. It is useful for whitespace-delimited languages like Python and other non-bracket-based languages.

The ii text object will select all code at the current level of indentation. The ai text object will select all code at the current level of indentation plus the line above it. For example, in Python, this would be like selecting the if statement which declared the indentation block.

The iI text object will select all code at the current level of indentation (just like ii). The aI text object will select all code at the current level of indentation plus the line above it plus the line below it. For example, in shell scripting, this would be like selecting the if statement which declared the indentation block and the closing endif line.

Sub-Word Text Object (camelcasemotion.vim) Plugin

camelcasemotion.vim is a vim plugin defined here:
https://github.com/bkad/CamelCaseMotion

Our Sub-Word Text Object plugin is based loosely on camelcasemotion.vim. Our plugin defines new motions and text objects for moving between words in snake_case_format and camelCaseFormat. It provides the following commands to be mapped:

• <Plug>(subword-back)
• <Plug>(subword-end)
• <Plug>(subword-word)

• <Plug>(subword-inner)
• <Plug>(subword-outer)

(subword-back), (subword-end), and (subword-word) motions are equivalent to the standard b, e, and w word motions. (subword-inner) will select the word between two _ characters of a snake_case_word. (subword-outer) will select the word between two _ characters and include the _ character(s) after that word. There is no difference between (subword-inner) and (subword-outer) for camelCaseWords.

A convenience command :subwordmappings will automatically configure the mappings:

• noremap <Leader>b <Plug>(subword-back)
• noremap <Leader>e <Plug>(subword-end)
• noremap <Leader>w <Plug>(subword-word)

• vnoremap i<Leader> <Plug>(subword-inner)
• onoremap i<Leader> <Plug>(subword-inner)
• vnoremap a<Leader> <Plug>(subword-outer)
• onoremap a<Leader> <Plug>(subword-outer)

By default, the value of <Leader> is \ but can be modified with the :let mapleader= command. Or, you can just define your mappings using whatever keys you want.

Cycle (cycle.vim) Plugin

cycle.vim is a vim plugin defined here:
https://github.com/zef/vim-cycle

Our cycle plugin provides the functionality to quickly replace the word under the cursor by cycling through a list of alternatives. It uses the keys <C-a> and <C-x>. As with all Ctrl key commands, you must Unbind <C-a> and <C-x> from Eclipse before Vrapper can use them. By default, this plugin defines the following cycles:

• yes, no
• true, false
• Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday
• January, February, March, April, May, June, July, August, September, October, November, December

If you put the cursor over the word true and hit <C-a> it will change the word to false. Hit <C-a> again and it will change false to true.
If the cursor is over the word Wednesday and you hit <C-a> it will change the word to Thursday. If the cursor is over the word Wednesday and you hit <C-x> it will change the word to Tuesday. If the cursor is over the word Wednesday and you hit 3<C-a> it will change the word to Saturday.

You can define your own custom cycles using the :AddCycleGroup command. For example:

• :AddCycleGroup foo bar baz

Will create a new cycle such that putting the cursor over the word foo and hitting <C-a> will change it to bar. Note that this plugin can only replace the single word under the cursor. It does not support replacing multiple words. Also, the word matching is case-sensitive.

Exchange (exchange.vim) Plugin

exchange.vim is a vim plugin defined here:
https://github.com/tommcdo/vim-exchange

Easy text exchange operator for Vim. Perform cx<text object> once to highlight a text object. Then perform cx<text object> again and the first (highlighted) text object will be swapped with the second text object. If you're using the same motion again (e.g. exchanging two words using cxiw), you can use . the second time.

The plugin provides the following commands:

Command	Mode	Description
cx<text object>	normal	highlight/exchange a text object
cxx	normal	highlight/exchange the current line
cxc	normal	clear previously highlighted text object
X	visual	highlight/exchange visual selection

The colour of the exchange region is configured in
Windows -> Preferences -> General -> Editors -> Text Editors -> Annotations -> Vrapper Exchange Region

NOTE: Block-wise visual selection is not implemented.

Sneak (Sneak.vim) Plugin

Sneak.vim is a vim plugin defined here:
https://github.com/justinmk/vim-sneak

This plugin defines a two-character search, faster than a / search but more versatile than a f or t single-character jump. To activate, type s followed by two characters that you want to search for. You can then go to the next/previous match with ; and , just like with f and t. Please see Sneak.vim's homepage for a better explanation of why this is beneficial.

Configuring this plugin requires mapping various <Plug>() commands. Here are the recommended mappings for your .vrapperrc:

• nmap s <Plug>(sneak_s)
• nmap S <Plug>(sneak_S)

• nmap ; <Plug>(sneak-next)
• nmap , <Plug>(sneak-prev)

• vmap s <Plug>(sneak_s)
• vmap Z <Plug>(sneak_S)

• vmap ; <Plug>(sneak-next)
• vmap , <Plug>(sneak-prev)

• nmap f <Plug>(sneak_f)
• nmap F <Plug>(sneak_F)
• nmap t <Plug>(sneak_t)
• nmap T <Plug>(sneak_T)

• vmap f <Plug>(sneak_f)
• vmap F <Plug>(sneak_F)
• vmap t <Plug>(sneak_t)
• vmap T <Plug>(sneak_T)

• omap z <Plug>(sneak_s)
• omap Z <Plug>(sneak_S)

Surround (surround.vim) Plugin

Surround.vim is a vim plugin defined here:
http://www.vim.org/scripts/script.php?script_id=1697
The Vrapper Surround plugin is a partial port of this script. The Vrapper Surround plugin can be invoked as the cs, ds and ys commands in normal mode, or as S and gS in visual mode. For these commands, the following replacements are supported:

• b ( )
• B { }
• [ ]
• '
• "
• `
• a >     (angle brackets, no whitespace)
• t <     (XML tags, asks for input)

A few examples:

1. Press ysE" to wrap all characters till the next space in double quotes (text objects can also be used, e.g. ysit").
2. Use cs"} to change those double quotes into curly brackets.
3. Pressing ds} will then remove the surrounding curly brackets.

Read the original script's documentation for more examples.

Custom delimiters

Surround.vim allows to introduce custom delimiters using variables. Vrapper has no support for such variables, so the surround command was introduced instead.

A few examples:

:surround - <?php\r?>

Introduces a new delimiter bound to -. The \r is a marker to know what the left and right bound should be.

:surround + <?php<SPACE>\r<SPACE>?>

Introduces a new delimiter bound to +, this time with extra spaces. Spaces MUST be specified as <SPACE>, otherwise the command parser will fail. A later version might fix this and simply allow the use of double quotes.

Surround with XML tags

The "surround with XML" feature asks for input to know which tags to place around the matched text. While this is similar with the original plugin, the Vrapper version has one custom feature, it allows to either ignore, add or override attributes.

For the following examples, assume that we are inside a tag <div class="comments" id="div1">...</div>.

Replace tag, keep attributes

1. Press cstt. The tag replace prompt pops up.
2. Enter <span

The attributes are untouched.

Replace tag, add attributes

1. Press cstt. The tag replace prompt pops up.
2. Enter <span style="float: left"

The tag is changed and an extra attribute is added at the front.

Change tag, replace attributes

1. Press cstt again.
2. Enter <span style="float:left" id="span">

Change tag, remove all attributes

1. Press cstt again.
2. Enter <span>