1. introduction
  2. basics
  3. commands
  4. search
  5. visual mode
  6. configuration
  7. commandline commands
  8. macros
  9. marks and registers
  10. optional plugins

Configuration

Settings

Vrapper's behaviour can be configured with command-line options.

You can find the current value of a property with :set <property>?

You can also use :setlocal to make a setting only applicable to this file (Eclipse tab) instance.

Vim Settings

These settings can be found in Vim and we've done our best to match the Vim behavior as closely as possible.

Command Short Default Description
:set smartindent
:set nosmartindent
:set si
:set nosi
On Whether to let the underlying editor indent lines or not. Overrides the autoindent option.
:set autoindent
:set noautoindent
:set ai
:set noai
Off Whether to indent inserted lines or not. When active, lines inserted with o or O will use the indent of the line under the cursor. cc or S will keep the whitespace at the beginning of a line.
:set ignorecase
:set noignorecase
:set ic
:set noic
Off Whether case should be ignored when searching.
:set smartcase
:set nosmartcase
:set scs
:set noscs
Off If set, searches will be case sensitive if the search string includes uppercase characters. Only used if ignorecase is set.
:set hlsearch
:set nohlsearch
:set hls
:set nohls
Off If set, search results will be highlighted.
:set incsearch
:set noincsearch
:set is
:set nois
Off Incremental search. If set, cursor will move to first closest match as you type.
:set list
:set nolist
none Off Show/Hide whitespace characters.
:set number
:set nonumber
:set nu
:set nonu
Off Show/Hide line numbers.
:set cursorline
:set nocursorline
:set cul
:set nocul
Off Show/Hide highlight on line with cursor.
:set autochdir
:set noautochdir
:set acd
:set noacd
Off Automatically change the current working directory to the parent of whatever file is currently active in Eclipse. The current working directory is used by the :e command.
:set scrolloff=<N> :set so=<N> scrolloff=0 When the cursor gets within <N> lines from the top or bottom of the view, perform a scrolljump.
:set scrolljump=<N> :set sj=<N> scrolljump=1 When the view needs to scroll, jump <N> lines at a time.
:set textwidth=<N> :set tw=<N> textwidth=80 Only used by the gq command to format paragraphs. Defines max line length when formatting.
:set softtabstop=<N> :set sts=<N> softtabstop=0 When using spaces for tabs, set this to the number of spaces inserted for each Tab key press and hitting Backspace in InsertMode will delete that many spaces as if you had deleted a tab character.
:set tabstop=<N> :set ts=<N> tabstop=8 Used by i_ctrl-t, i_ctrl-d, and :retab. Determines number of spaces to replace each tab character with when expandtab is enabled.
:set expandtab
:set noexpandtab
:set et
:set noet
On Used by i_ctrl-t, i_ctrl-d, and :retab. Determines whether :retab should replace all tabs with spaces (true) or spaces with tabs (false). Also determines whether i_ctrl-t and i_ctrl-d will replace tabstop spaces with a tab.
:set shiftround
:set noshiftround
:set sr
:set nosr
Off Round indent (i_ctrl-t, i_ctrl-d, >> and <<) to the nearest multiple of shiftwidth.
:set shiftwidth=<N> :set sw=<N> shiftwidth=8 Used by i_ctrl-t, i_ctrl-d, >, and < commands. Determines how many spaces are used for each indent added or removed.
:set path=<comma-delimited list of dirs> none path=. List of directories searched during the :find <filename> command. Default directory of . represents directory of the current active file in Eclipse. A path may end in ** to represent "all sub-directories".
For example, :set path=src/main/java/**
:set iskeyword=<regex of word characters> :set isk=<characters> iskeyword=a-zA-Z0-9_ Regex of character-classes which should be treated as word characters. This will be interpreted as the regex [<iskeyword value>]. All contiguous characters matching this regex will be treated as one word for w and * commands.
This property can also be modified with += and -= (e.g., :set isk+=.)
:set clipboard=<name> none clipboard=autoselect :set clipboard=unnamed will use the system clipboard (also known as "+) for all y and p operations.
:set clipboard=autoselect will use the standard "* clipboard.

Vrapper Settings

These settings are specific to Vrapper (not found in Vim). They either help with managing Eclipse behavior or they were feature requests from our community which we implemented.

Command Short Default Description
:set globalregisters
:set noglobalregisters
none On Whether registers (including the last search, last character search and last edit) should be shared across all editors of the workbench or local to the editor.
:set atomicinsert
:set noatomicinsert
:set ati
:set noati
On Whether inserts should be handled as atomic operation. This causes problems sometimes, so it is deactivatable.
:set regexsearch
:set noregexsearch
:set rxs
:set norxs
On If set, keywords will be handled as (Eclipse style) regular expressions.
:set sanecw
:set nosanecw
none Off If set, cw deletes the same as dw (i.e. whitespace before the next word is not spared).
:set saney
:set nosaney
none Off If set, Y will yank from the cursor position to the end of the line instead of yanking the whole line.
:set visualmouse
:set novisualmouse
none On If set, selecting text with the mouse will automatically move into Visual Mode.
:set gvimpath=<path to gvim executable> none gvimpath=/usr/bin/gvim Defines path to gvim used with :vim command.
:set gvimargs=<arguments for gvim executable> none gvimargs=+{line} -c normal zv{col}| -c set nobackup -f -n {file} Defines arguments to send to gvim when using :vim command. Supports placeholder strings {line}, {col}, and {file} which define current cursor position and filename in Eclipse.
:set cleanindent
:set nocleanindent
none On If you create a new line with o while autoindent is enabled, that new line will be indented. If you then exit insert mode without entering any text, that auto-indent is typically removed (leaving only a blank line). Disable cleanindent if you don't want it to cleanup that auto-indent.
:set exitlinkmode
:set noexitlinkmode
:set elm
:set noelm
On If set, Vrapper will return to NormalMode anytime Eclipse exits its "Link Mode". Eclipse moves into Link Mode when prompting you to fill out arguments. This typically means Eclipse has drawn a box around some words and it wants you to fill them in.
:set contentassistmode
:set nocontentassistmode
:set cam
:set nocam
Off Enables c-n and c-p to move selection up and down in the content-assist dropdown.
Use camap to map other keys to c-n or c-p.
:set startnormalmode
:set nostartnormalmode
:set snm
:set nosnm
Off When enabled, always start in NormalMode after changing tabs. For example, if you go into InsertMode, change tabs to another file, then change tabs back, you will be in NormalMode (exit InsertMode).
:set imdisable
:set noimdisable
none Off If set, exiting Insert Mode will automatically disable the Input Method (useful on Japanese keyboards).

Remapping Keys

There are a lot of commands for defining different key mappings, but essentially four actions: create a mapping which is searched again for other mappings, create one which is not mapped again, clear a mapping, and clear all mappings. Each of these four actions can be done either for normal and visual mode together or for one of normal, visual, or insert mode alone. The commands are:

Command Description
:map <lhs><rhs> Maps <lhs> to <rhs>. Searches <rhs> for more mappings.
:noremap <lhs> <rhs>
:no <lhs> <rhs>
Maps <lhs> to <rhs>. Ignores mappings occuring in <rhs>
:unmap <mapping> :unm <mapping> Removes the mapping for <mapping>.
:mapclear
:mapc
Removes all mappings of the corresponding key map.

The commands above all manipulate the key maps of normal and visual mode respectively. The following commands are used for the individual modes:

nmap
nm
imap
im
omap
om
vmap
vm
nnoremap
nn
inoremap
ino
onoremap
ono
vnoremap
vn
nunmap
nun
iunmap
iu
ounmap
ou
vunmap
vu
unmap
unm
nmapclear
nmapc
imapclear
imapc
omapclear
omapc
vmapclear
vmapc
mapclear
mapc

It is possible to map multiple keys to multiple other keys, e.g. :ino jj <ESC> or :nn cw ce.

Special characters can be mapped by using the notation <NAME>. Control characters are mapped by using <C-x>, where x is a character from A-Z. Similarly, Alt (meta) characters are mapped by using <A-x> or <M-x>. Shift characters are mapped by using <S-x> but only the special keys are supported. Here is a list of special character names:

  • F1 to F12
  • GT
  • LT
  • LEFT*
  • RIGHT*
  • UP*
  • DOWN*
  • ENTER
  • RETURN*
  • ESC*
  • HOME
  • END
  • PAGE_UP
  • PAGE_DOWN
  • INSERT
  • DELETE
  • BACKSPACE*
  • SPACE
  • BAR
* InsertMode can only understand the special character names marked with an asterisk. For example, :inoremap <C-E> <DELETE> won't currently do anything.

Collisions between Vrapper and Eclipse bindings

If a key combination is already mapped by Eclipse (e.g. Ctrl-P on Windows and Linux based systems is mapped to print), Vrapper will not receive the keystroke, so mapping it to some Vrapper action will not work.

In Eclipse, go to the Preferences window, then General -> Keys. Find the binding causing the collision. Select it, then click the "Unbind Command" button. This should remove the binding in the "Binding" column. Click "Apply". Vrapper should now receive the keystrokes and your mapping should work correctly.

Configuration File

The options described above only change the behaviour of the editor in which they are set. To change the default configuration, a file is used. When a new editor is opened, the plugin checks for a file called .vrapperrc in the user's home directory (or _vrapperrc to make it easier for Windows people). If found, the commands in the file are executed. You may use any configuration command in this file. As with .vimrc files, the leading : is omitted in the configuration file.

This is an example of the contents of a configuration file:

noremap d h
noremap h j
noremap t k
noremap n l
noremap e d
noremap E D
noremap l n
noremap L N
noremap s :
noremap ` ^
noremap k e
noremap K E
set autoindent
set ignorecase
set smartcase