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
  1. Settings
    1. Vim Settings
    2. Vrapper Settings
  2. Re-Mapping Keys
  3. Configuration File

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 spell
:set nospell		 none Off Show/Hide spell-checking highlights.
: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_\u00C0-\u017F Regex of character-classes which should be treated as word characters. This will be interpreted as a regex character class (for example, [a-zA-Z0-9_]). 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= This setting is a multi-valued string setting. You can specify any of the following separated by a comma:
  • unnamed will make Vrapper use the selection clipboard (also known as "*) for all y and p operations on Linux. On Windows and Mac the system clipboard (known as "+) will be used instead because they do not have a selection clipboard.
  • unnamedplus will make Vrapper use the system clipboard (also known as "+) for all y and p operations.
  • autoselect will copy selected text directly to the selection clipboard whenever the selection is changed inside Vrapper's visual modes. On Windows and Mac, the system clipboard will be used.
  • autoselectplus will copy selected text directly to the system clipboard whenever the selection is changed inside Vrapper's visual modes.
  • exclude: is a value which is only added for compatibility with Vim. It is silently ignored which means you can safely set it in any shared RC file. Vim expects some more text after the colon which is also ignored by Vrapper.
Multiple values can be specified (e.g. :set clipboard=unnamed,unnamedplus,exclude:console). If so, both the system as well as the selection clipboard should get updated.
:set modifiable
:set nomodifiable		 :set ma
:set noma		 On (Editor local) Whether the current file can be modified. If unset, Vrapper will print the following error in the statusline: Cannot modify contents, 'modifiable' is off!
Note that certain editors are completely read-only (e.g. Java class viewers), for these editors the 'modifiable' setting has no effect. Vrapper will always print the following error when trying to modify such a file: Cannot modify contents, file is not editable!. If you want to edit such a file, try copying the contents to a new file and edit that file instead.
:set wrapscan
:set nowrapscan		 :set ws
:set nows		 On When enabled, search will wrap around the bottom/top of a file to find the next match.

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 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).
:set syncmodifiable=<sync type> :set syncma=... nosync Vrapper can set its internal 'modifiable' flag based on the current editor's state.
Currently these sync types are supported:
matchreadonly
Checks the editor's readonly flag.
nosync
Disables this feature completely. Perforce plugin users might want to set this.
When set to nosync, a read-only file can be edited and Eclipse will ask if you want to save to another file.
This is a global setting, and any opened editor must be re-opened before this setting takes effect. You might want to manually set modifiable if Vrapper gets it wrong.
:set hlscope=<highlight mode> none clear This setting changes the behavior of the hlsearch setting to restrict it to a number of editors. Whereas Vim will always quickly highlight the current search across all windows and tabs, in Vrapper this might take quite some time and resources. To tune the performance, the following values are supported:
clear
Only one editor can have active highlighting. Switching might change the highlighting if an editor gets reloaded, but normally the highlighting only changes if running a search in the current active editor.
local
Each editor gets its own highlighting, Vrapper will not clear or update it if doing anything in another editor.
window
All editors in the current window will use the same highlighting except for those which have noglobalregisters set (those use a local search register).
Note that the above might behave weirdly if you open fresh editors or switch to an editor from your last session. This is a known issue and will be improved in due time.

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>. The Mac Command key can be mapped using <D-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.
Defining maps for Eclipse operations

You can define maps to execute Eclipse operations using :eclipseaction and :eclipseuiaction as described on the Commandline Commands page. You can also use the <Plug>() syntax, though this is typically only used in a .vrapperrc file (see the Configuration File section below).

Here are some examples using the <Plug>() syntax:

  • noremap \w <Plug>(eclipse-motion:org.eclipse.ui.edit.text.goto.wordNext)
  • noremap \b <Plug>(eclipse-motion:org.eclipse.ui.edit.text.goto.wordPrevious)
  • noremap \e <Plug>(eclipse-textobj:org.eclipse.jdt.ui.edit.text.java.select.enclosing)
  • noremap \l <Plug>(eclipse-textobj:org.eclipse.jdt.ui.edit.text.java.select.last)

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 (or _vrapperrc to make it easier for Windows people). This file is expected to be in the user's HOME directory but may be overridden by setting the system property vrapper.vrapperrc when launching Eclipse (-Dvrapper.vrapperrc=<file>). If this file is found, the commands in the file are executed. You may use any configuration command in this file. As with .vimrc files, the leading : may be 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
    imap jj <esc>
    map L $
    map H ^
    set autoindent
    set ignorecase
    set smartcase