Plugin to work with R
Authors: Jakson A. Aquino <email@example.com>
Jose Claudio Faria
For Vim version 7.3
1. Overview r-plugin-overview
2. Main features r-plugin-features
3. Installation r-plugin-installation
4. Use r-plugin-use
5. How the plugin works r-plugin-functioning
6. Known bugs and workarounds r-plugin-known-bugs
7. Options r-plugin-options
8. Custom key bindings r-plugin-key-bindings
9. Files r-plugin-files
10. FAQ and tips r-plugin-tips
11. News r-plugin-news
This plugin improves Vim's support for editing R code and makes it possible to
integrate Vim with R.
It uses some ideas and code from Johannes Ranke's (vim-r-plugin), Eric Van
Dewoestine's (screen plugin), Vincent Nijs (R.vim for Mac OS X) and some ideas
from the Tinn-R (Windows only) project.
The latest version of this plugin is available at:
Feedback is welcomed. Please submit bug reports and feature requests to the
developers, we are very interested in what you like and what you would like to
see in future releases. Do not like a feature? Tell us and we may add an
option to disable it. Cryptic error message are bugs... Please report them.
The plugin should emit useful warnings if you do things it was not programmed
to deal with.
2. Main features
* Syntax highlighting for R syntax, including:
- Special characters in strings.
- Functions of all installed packages (must be updated manually).
- Special highlighting for R output (.Rout files).
- Spell check only strings and comments.
- Fold code when foldmethod=syntax.
* Smart indentation for R syntax.
* Integrated communication with R:
- Start/Close R.
- Send lines, selection, paragraphs, functions, blocks, entire file.
- Send commands with the object under cursor as argument: help, args,
plot, print, str, summary, example, names.
- Send to R the Sweave and pdflatex commands.
- Run R inside a Vim's buffer.
* Omni completion (auto-completion) for R objects (.GlobalEnv and installed
packages. The list of installed packages must be updated manually.
* Ability to see R's documentation in a Vim's buffer:
- Automatic calculation of the best layout of the R documentation buffer
(split the window either horizontally or vertically according to the
- Automatic formating of the text to fit the panel width.
- Send code and commands to R (useful to run examples).
- Jump to another R documentation.
- Syntax highlighting of R documentation.
* Object Browser (.GlobalEnv and loaded packages; must be updated manually):
- Send commands with the object under cursor as argument.
- Call R's help() with the object under cursor as argument.
- Syntax highlighting of the Object Browser.
* Most of the plugin's behavior is customizable.
3.1. General instructions I
You need to activate plugins and indentation according to 'filetype'. You
should have at least the following options in your vimrc:
Make a backup of your ~/.vim directory because existing files will be
replaced. Please, look at r-plugin-files to see the list of files.
3.2. Operating system specific instructions
3.2.1. Unix (Linux, OS X, etc.)
In addition to having R installed in your system, this plugin requires users
to install either:
Conque Shell: http://www.vim.org/scripts/script.php?script_id=2771
or screen: http://www.gnu.org/software/screen
Note: The screen application is already packaged for most GNU/Linux
distributions and other Unix variants. In fact, screen is installed by
default on many Linux distributions. Unfortunately, installation
instructions for these dependencies vary widely and are beyond the scope of
Uncompress the archive:
Start Vim and build the tags file for this document (and others that eventually
are in at the same directory):
You may be interested in integrating the Vim-R-plugin with either screen.vim
plugin or Conque Shell plugin. See vimrplugin_screenplugin and
vimrplugin_conqueplugin for details.
In addition to having R installed in your system, this plugin requires users
to install several external dependencies:
* Vim's version must be >= 7.3
* Python: http://www.python.org/download/
Note: Be careful to download the correct Python version because Vim
needs a specific version of Python DLL. For example, the official Vim
7.3 for Windows needs either Python 2.7 or 3.1. Note: the official Vim
is 32 bit and, thus, Python must be 32 bit too.
* pywin32: http://sourceforge.net/projects/pywin32/
Note: The default download may not match the Python version Vim was
linked with. You have to "View all files" on the download page to find
the file that matches the version of Python that you installed.
Create your vimfiles directory if you do not have it yet. Its path will be
similar to one of the following:
Uncompress the archive. Right click on the plugin's zip file and choose
"Extract all". Then choose ~/vimfiles as the destination directory.
Start Vim and build the tags file for this document (and others that eventually
are in the same directory):
Start R and try to send some lines from GVim to R Console. You may have to
adjust the value of vimrplugin_sleeptime.
3.3. Troubleshooting (if the plugin doesn't work)
The plugin is a file-type plugin. It will be active only if you are editing
a .R or .Rnw file. The menu items and tool bar buttons will not be visible and
the key bindings will not be active while editing either unnamed files or
files with name extensions other than .R or .Rnw. If the plugin is active,
pressing <LocalLeader>rf should start R (the <LocalLeader> is '\' by default).
Look at the ~/.vim (Linux, Unix, Os X) or ~/vimfiles (Windows) directory. Is
there a subdirectory named "r-plugin"? If not, then you unpacked the plugin in
the wrong place.
Did you see warning messages but they disappeared before you have had time to
read them? Type the command :messages in Normal mode to see them again.
Are you using Debian, Ubuntu or other Debian based Linux distribution? If yes,
you may prefer to install the Debian package available at:
3.4. General instructions II (optional steps)
update list of objects
Start R and update the list of objects for omni completion and syntax
highlight (see :RUpdateObjList for details).
customize the plugin
Please, read the section r-plugin-options.
hide unused buttons
Edit Vim's toolbar and remove the buttons that you never use. The plugin adds
some buttons to the toolbar, but you may not see them because gvim has too
many buttons by default. Please see the page below to know how to hide buttons
on the toolbar:
install additional plugins
You may be interested in installing additional general plugins to get
functionality not provided by this file type plugin. ShowMarks, snipMate, and
EnhancedCommentify are particularly interesting. Please read r-plugin-tips
4.1. Key bindings
To use the plugin, open a .R or .Rnw or .Rd file with Vim and type \rf
(replace \ with the key used as <LocalLeader>). Then, you will be able to use
plugin key bindings to send commands to R.
This plugin has many key bindings, which correspond with menu entries and, in
some cases, toolbar buttons. In the list below, the backslash represents the
<LocalLeader> (see maplocalleader). Not all menu items and key bindings are
enabled in all filetypes supported by the plugin (r, rnoweb, rhelp):
. Start R (default) \rf
. Start R --vanilla \rv
. Start R (custom) \rc
. Close R (no save) \rq
. Close R (save workspace) \rw
. File \aa
. File (echo) \ae
. File (open .Rout) \ao
. Block (cur) \bb
. Block (cur, echo) \be
. Block (cur, down) \bd
. Block (cur, echo and down) \ba
. Function (cur) \ff
. Function (cur, echo) \fe
. Function (cur and down) \fd
. Function (cur, echo and down) \fa
. Selection \ss
. Selection (echo) \se
. Selection (and down) \sd
. Selection (echo and down) \sa
. Paragraph \pp
. Paragraph (echo) \pe
. Paragraph (and down) \pd
. Paragraph (echo and down) \pa
. Line \l
. Line (and down) \d
. Line (and new one) \q
. List space \rl
. Clear console \rr
. Clear all \rm
. Object (print) \rp
. Object (names) \rn
. Object (str) \rt
. Arguments (cur) \ra
. Example (cur) \re
. Help (cur) \rh
. Summary (cur) \rs
. Plot (cur) \rg
. Plot and summary (cur) \rb
. Update Object Browser \ro
. Set working directory (cur file path) \rd
. Build R tags file :RBuildTags
. Build omniList (loaded packages) :RUpdateObjList
. Build omniList (installed packages) :RUpdateObjListAll
. Sweave (cur file) \sw
. Sweave and PDF (cur file) \sp
. Go to next R chunk gn
. Go to previous R chunk gN
Please see r-plugin-key-bindings to learn how to customize the key bindings
without editing the plugin directly, and vimrplugin_underscore to disable
After the command \ao, Vim will save the current buffer if it has any pending
changes, run "R CMD BATCH --no-restore --no-save" on the current file and show
the resulting .Rout file in a new tab. Please see vimrplugin_routnotab if
you prefer that the file is open in a new split window. Note: The command
\ao, silently writes the current buffer to its file if it was modified and
deletes the .Rout file if it exists.
R syntax uses " <- " to assign values to variables which is inconvenient to
type. In insert mode, typing a single underscore, "_", will write " <- ",
unless you are typing inside a string. If necessary, it is possible to insert
an actual underscore into your file by typing a second underscore. This
behavior is similar to the EMACS ESS mode some users may be familiar with and
is enabled by default.
4.2. Edition of rnoweb files
In Rnoweb files (.Rnw), when the cursor is over the @ character, which
finishes an R chunk, the sending of all commands to R is suspended and the
shortcut to send the current line makes the cursor to jump to the next chunk.
While editing rnoweb files, the following commands are available in Normal
gn : go to the next chunk of R code
gN : go to the previous chunk of R code
4.3. Omni completion and the highlighting of functions
The plugin adds some features to the default syntax highlight of R code. One
such feature is the highlight of R functions. However, only functions that
R loads by default are highlighted. To add functions of other libraries, you
should do the following:
1. Start R from within Vim.
2. Use R's library() to load the libraries whose functions you want
3. Run the following command in Vim's Normal mode:
The command :RUpdateObjList in addition to creating a list of function names
to be highlighted also creates a file containing a list of objects for omni
completion (compl-omni) including all objects currently in R's workspace,
with the exception of the .GlobalEnv objects. These two lists are stored
permanently in the ~/.vim/r-plugin directory and one of them, "omniList", is
also used by the Object Browser to show the contents of libraries.
The command :RUpdateObjList waits 120 seconds to R finish building the list.
If this time is not enough to your system, please, set a different value of
You should run :RUpdateObjList whenever you upgrade R since some functions
are removed and new ones are added at each new R version.
The command :RUpdateObjListAll will tell R to load all installed packages
and, then, build the "omniList".
4.4. The Object Browser
You have to do \ro to either start or updated the Object Browser. The Object
Browser has two views: .GlobalEnv and Libraries. If you either press <Enter>
or double click on the first line of the Object Browser it will toggle the
view between the objects in .GlobalEnv and the currently loaded libraries (but
only libraries loaded when :RUpdateObjList was run will be shown).
In the .GlobalEnv view, if an object has the attribute "label", it will be
displayed in the Object Browser. The options vimrplugin_open_df and
vimrplugin_open_list control whether the elements of data.frames and lists
are shown. In the Object Browser window, while in Normal mode, you can either
press <Enter> or double click (GVim only) over a data.frame or list to
show/hide its elements (not if viewing the content of loaded libraries). If
you are running (G)Vim in an UTF-8 locale, unicode line drawing characters
will be used to draw lines in the Object Browser. This is the case of most
Linux distributions. If you are using Windows, ascii characters will be used,
unless you have set the 'encoding' to utf-8 in your vimrc (on Windows, some
fonts that support Unicode are "Courier_New", "Lucida_Console", "Consolas",
In the Libraries view, you can either double click or press <Enter> over a
library to see its objects. The Object Browser goes down only one level in
lists. Thus, if a list has a sublist among its elements, the sublist elements
will not be shown. In the Object Browser, the libraries have the color defined
by the PreProc highlighting group, and the other objects have their colors
defined by the return value of some R functions. Each line in the table below
shows a highlighting group and the corresponding R function (if any) used to
classify the objects:
4.5. Build a tags file to jump to function definitions
Vim can jump to functions defined in other files if you press CTRL-] over the
name of a function, but it needs a tags file to be able to find the function
definition (see tags-and-searches). The command :RBuildTags call the R
function rtags() to build the tags file for the R scripts in the current
directory. Please read the r-plugin-tips to learn how to create a tags file
referencing source code located in other directories, including the entire R
5. How the plugin works
5.1. Omni completion
Vim can automatically complete the names of R objects when CTRL-X CTRL-O is
pressed in insert mode (see omni-completion for details and 'completeopt' to
know how to customize the omni-completion). Omni completion shows in a pop
up menu the name of the object, its class and its environment (most
frequently, its package name). If the object is a function, its arguments are
shown in a separate window.
If a data.frame is found, while building the list of objects, the columns in
the data.frame are added to the list. When you try to use omni completion to
complete the name of a data.frame, the columns are not shown. But when the
data.frame name is already complete, and you have inserted the '$' symbol,
omni completion will show the column names.
The file containing the list of objects used for omni completion is built by
the R function contained in the script ~/.vim/r-plugin/buil_omniList.R. This
function is sourced by R, which causes R to create the list used by Vim.
Vim uses two files: one for the objects of .GlobalEnv and the other for all
other objects. The .GlobalEnv list is stored in the /tmp/r-plugin-yourlogin
directory and, thus, is deleted after each reboot. The other file is stored in
~/.vim/r-plugin and remains available until you manually rebuild it with the
5.2. Communication through screen, without the screen plugin (Linux/Unix only)
Vim and R run as independent processes. The main disadvantage is that we have
limited communication between the two applications: Vim can send strings to R
through screen and R can write files to be read by Vim. That's all. The main
advantage is that Vim's or the plugin's bugs will not affect R.
The r-plugin uses screen to communicate with R. First, the plugin initiates a
new screen session and uses this to start a new R process. The plugin's menu
options, toolbar buttons and key bindings can then be used to communicate with
the newly started R process. The plugin sends commands to R through screen. By
default, all Vim buffers share the same R process, but it is also possible to
configure Vim so that each buffer runs its own instance of R in a separate
terminal emulator. In this case, the screen sessions have unique names. The
names are made using the user name and the seconds of localtime(). Hence, a
name clash is possible if a single user starts more than one Vim buffer at the
same second. To change the default behavior and force all Vim buffers to use
different R processes see vimrplugin_single_r.
6. Known bugs and workarounds
Correctly written code might be wrongly indented. Example:
this code is indented as:
for(i in 1:2) for(i in 1:2)
cat(i, "\n") cat(i, "\n")
6.2. R's source() issues
The R's source() function prints an extra new line between commands if the
option echo = TRUE, and error messages and warning are printed only after the
entire code is sourced, which makes it more difficult to find errors in the
code sent to R.
6.3. GVim's toolbar buttons, menu and title bar blink during omni completion
The plugin unmakes the R menu and the related toolbar buttons when Vim leaves
the R buffer. During omni completion, Vim leaves the R buffer and goes to the
scratch window which is not recognized as an R file type. Consequently, the
plugin unmakes the toolbar buttons and R related menu items. If you prefer,
you can use the option vimrplugin_never_unmake_menu but, then, the menu and
tool bar buttons will never be deleted, even if you change from one file type
6.4. R session is detached when GVim is closed (Linux/Unix only)
If you launch GVim through a custom keyboard shortcut, the problem may be
solved if you add -f as parameter to GVim. The R session will also be detached
when GVim is closed if you launch GVim by the command line in a terminal
emulator, and, then, close the terminal-emulator. In any case, to reattach to
the R session, open a new terminal window and type:
6.5. The clipboard's content is lost (Windows only)
On Windows, the plugin copies the command that will be sent to R into the
clipboard when not using the Conque Shell plugin. Thus, if you have anything
in the clipboard it will be lost while using the plugin.
6.6. The buffer name must be in the window title (Windows only)
On Windows, when not using the Conque Shell plugin, the plugin tries to
activate the "R Console" window, paste the command that is being sent to R,
and, then, activate the GVim window. To activate the GVim window the plugin
requires that the name of the file being edited be in the GVim windows title.
This is the default on Vim if you have not set the option 'titlestring'.
6.7. The menu may not reflect some of your custom key bindings
If you have created a custom key binding for the Vim-R-plugin, the menu in
GVim will not always reflect the correct key binding if it is not the same for
Normal, Visual and Insert modes.
6.7. quit(save = "yes") may not work properly
If you are using either the Conque Shell plugin or the Screen plugin (and are
not running R in an external terminal), the R command quit(save = "yes") may
not have time enough to save the workspace. Vim will sleep for 1 second after
the command \rw before killing R but this time is not enough for big
vimrplugin_term External terminal to be used
vimrplugin_term_cmd Complete command to open an external terminal
vimrplugin_underscore Convert '_' into ' <- '
vimrplugin_rnowebchunk Convert '<' into '<<>>=\n@' in Rnoweb files
vimrplugin_objbr_place Placement of Object Browser
vimrplugin_objbr_w Initial width of Object Browser window
vimrplugin_vimpager Use Vim to see R documentation
vimrplugin_editor_w Minimum width of R script buffer
vimrplugin_help_w Desired width of R documentation buffer
vimrplugin_nosingler A single R process for all Vim instances
vimrplugin_by_vim_instance Each Vim instance runs its own R
vimrplugin_i386 Use 32 bit version of R
vimrplugin_r_path Directory where R is
vimrplugin_r_args Arguments to pass to R
vimrplugin_buildwait Time to wait for :RUpdateObjList to finish
vimrplugin_routmorecolors More syntax highlighting in R output
vimrplugin_routnotab Show output of R CMD BATCH in new window
vimrplugin_sleeptime Delay while sending commands in MS Windows
vimrplugin_noscreenrc Do not write custom screenrc
vimrplugin_screenplugin Use the screen plugin
vimrplugin_screenvsplit Split the window vertically with screen plugin
vimrplugin_conqueplugin Use the Conque Shell plugin
vimrplugin_conquevsplit Split the window vertically for Conque Shell
vimrplugin_conquesleep Time that Conque Shell will wait for output
vimrplugin_applescript Use osascript in Mac OS X.
vimrplugin_open_df Show data.frame elements in the Object Browser
vimrplugin_open_list Show list elements in the Object Browser
vimrplugin_allnames Show names which begin with a dot
vimrplugin_listmethods Do .vim.list.args() instead of args()
vimrplugin_specialplot Do .vim.plot() instead of plot()
vimrplugin_maxdeparse Argument to R args() function
vimrplugin_latexcmd Command to run on .tex files
vimrplugin_never_unmake_menu Do not unmake menu when switching buffers
vimrplugin_map_r Use 'r' to send lines and selected text
7.1. Terminal emulator (Linux/Unix only)
The plugin uses the first terminal emulator that it finds in the following
If Vim does not select your favorite terminal emulator, you may define it in
your vimrc by setting the variable vimrplugin_term, as shown below:
If your terminal emulator is not listed above, or if you are not satisfied
with the way your terminal emulator is called by the plugin, you may define in
your vimrc the variable vimrplugin_term_cmd, as in the example below:
Please, look at the manual of your terminal emulator to know how to call it.
The last argument must be the one which precedes the command to be executed.
7.2. Underscore and Rnoweb completion of code block
While editing R code, '_' is replace with ' <- '. To disable this feature, put
in your vimrc:
In Rnoweb files, a '<' is replaced with '<<>>=\n@'. To disable this feature,
put in your vimrc:
7.3. Object Browser options
The Object Browser may be created in four different places: at the right/left
of the script windows or (if using Conque Shell) at the right/left of the R
Console window (see vimrplugin_conqueplugin for details on the use of Conque
Shell). By default, the Object Browser will be created with 40 columns at the
right side of the R Console. If Conque Shell is not being used, the Object
Browser will be at the right side of the script window. You can change the
Object Browser's default width and placement by putting different values in
your vimrc, as in the examples below:
The minimum width of the Object Browser windows is 9 columns.
By default, the elements of data.frames are shown in the Object Browser, but
not the elements of other types of lists. You can put the following in your
vimrc to change this behavior:
By default, names of objects which begin with a . are omitted. If you prefer
to see them in the Object Browser, put in your vimrc:
7.4. Vim as pager for R help
7.4.1. Quick setup
If you do not want to see R documentation in a Vim's buffer, put in your
7.4.2. Details and other options:
The plugin key bindings will remain active in the documentation buffer, and,
thus, you will be able to send commands to R as you do while editing an R
script. You can, for example, use <LocalLeader>rh to jump to another R help
The valid values of vimrplugin_vimpager are:
"horizontal": Split the window horizontally.
"vertical" : Split the window vertically if the editor width is large
enough; otherwise, split the window horizontally and attempt
to set the window height to at least 20 lines.
This is the default.
"tab" : Show the help document in a new tab. If there is already a
tab with an R help document, use it.
"tabnew" : Show the help document in a new tab.
"no" : Do not show R documentation in Vim.
The window will be considered large enough if it has more columns than
vimrplugin_editor_w + vimrplugin_help_w. These variables control the minimum
width of the editor window and the help window, and their default values are,
respectively, 66 and 46. Thus, if you want to have more control over Vim's
behavior while opening R's documentations, you will want to set different
values to some variables in your vimrc, as in the example:
7.5. Number of R processes (Linux/Unix only)
7.5.1 Using (G)Vim without the Conque Shell plugin or the Screen plugin
By default, all buffers of all (G)Vim instances send code to the same R process.
If you prefer that each Vim buffer uses its own R process, put the following
option in your vimrc:
If you prefer that each Vim instance calls its own R process and all of the
instance's buffers send code to this R process while other Vim instances send
code to other R processes then put the following in your vimrc:
The vimrplugin_by_vim_instance option requires that Vim is acting as a
command server because the variable v:servername is used to make the name of
the screen session which will run R. By default, GVim runs as server, but Vim
does not. Hence, if you are using Vim you have either to start Vim with the
argument --servername or use the screen.vim plugin which tries to restart Vim
with the --servername argument. If you want to use more than nine GVim
instances you will have to use the --servername argument because screen will
not differentiate between the names "GVIM1" and "GVIM10".
7.5.2 Using the Screen plugin
Both options are ignored when using Vim in a terminal emulator and using
the Screen plugin. The plugin behaves as if the vimrplugin_by_instance was
7.5.3 Using the Conque Shell plugin
By default, each Vim buffer sends code to its own R process. You can set
vimrplugin_by_vim_instance value to 1 if you prefer that all buffers of each
(G)Vim instance sends code to the same R process. When using the Conque Shell
plugin, there is no need of setting a Vim server because R will be running
inside a Vim's buffer, and, thus, Vim has direct access to R's input and
The option vimrplugin_nosingler is ignored.
7.6. Use 32 bit version of R (Windows and Mac OS X only)
If you are using a 64 bit Windows or a 64 bit Mac OS X, but prefer to run the
32 bit version of R, put in your vimrc:
7.7. R path
Vim will run the first R executable in the path. You can set an alternative R
path in your vimrc as in the examples:
On Windows, Vim will try to find the R install path in the Windows Registry.
7.8. Arguments to R
Set this option in your vimrc if you want to pass command line arguments to
R at the startup. Example:
On Linux, there is no default value for vimrplugin_r_args. On Windows, the
default value is "--sdi", but you may change it to "--mdi" if you do not like
the SDI style of the graphical user interface.
7.9. Time necessary to build list of objects for omni completion
If your system needs more than 120 seconds to build the list of objects for
omni completion after you do the command :RUpdateObjList, then you should
set the value of vimrplugin_buildwait to a higher value. Example:
7.10. More colorful syntax highlight of .Rout files
By default, the R commands in .Rout files are highlighted with the color of
comments, and only the output of commands has some of its elements highlighted
(numbers, strings, index of vectors, warnings and errors). The same
highlighting scheme is applied to the R Console when using the Conque Shell
plugin to run R inside a Vim's buffer. For one hand, we do not need to
highlight R commands in the Console if they were sent by the plugin from an R
script buffer since we have the code highlighted in the script buffer and in
the Console we want to pay attention to the output. A too colorful
highlighting scheme would be distracting. On the other hand, if we were typing
commands directly in the Console it would be beneficial to have the R syntax
If you prefer that R commands in the R output are highlighted as they are in R
scripts, put the following in your vimrc:
7.11. How to automatically open the .Rout file
After the command \ao, Vim will save the current buffer if it has any pending
changes, run "R CMD BATCH --no-restore --no-save" on the current file and show
the resulting .Rout file in a new tab. If you prefer that the file is open in
a new split window, put in your vimrc:
7.12. Sleep time (Windows only)
The plugin gives to R a small amount of time to process the paste command when
not using the Conque Shell plugin. The default value is 0.2 second, but you
should experiment different values. The example show how to adjust the value
of sleeptime in your vimrc:
7.13. Screen configuration (Linux/Unix only)
Vim runs screen with a special configuration file. If you want to use
your own ~/.screenrc, put in your vimrc:
7.14. Integration with screen.vim (Linux/Unix only)
By default, Vim-R-plugin will use the screen.vim plugin if it is installed
unless Conque Shell plugin is installed too. If you prefer to use both
Vim-R-plugin and screen plugin at the same time, download and install the
Start Vim and do the command <LocalLeader>rf. The screen plugin will split the
terminal in two regions and will run R in one of them. Using both plugins at
the same time is especially useful for users who may prefer to use Vim and R
in a terminal emulator, rather than using the graphical interface provided by
If you have the screen plugin installed but prefer do not integrate the it
with the Vim-R-plugin you will need to add the following to your vimrc:
The screen.vim plugin also supports tmux, which allows you to split the
terminal vertically. Please read screen-intro and screen-shell-vertical
for details. By default, the Vim-R-plugin will tell the screen plugin to
split the terminal horizontally. If you preffer to split it vertically,
install tmux and put in your vimrc:
Note that the second line is an option of the screen plugin and that it is
also possible to split the terminal vertically if using the correct version of
the screen application (see screen-shell-vertical).
Note: Read the screen's documentation, especially the section screen-gotchas
(the E325 is caused by the presence of 'swapfile'). This problem will not
happen if you start Vim from within a screen session, as in the example below.
However, when starting Vim from within screen you will not be able to start a
new R session after closing the first one with the \rq command. Moreover, you
will have to manually switch from one screen region to another and kill them.
A sample detachable session could be:
- Start Vim through screen:
screen vim theScript.R
- Use Vim to start an R session:
- Send code from Vim to R, and, then, detach Vim and R with <c-a>d
- Some time latter reattach the screen session:
- Type <c-a>S to split the region, <c-a><tab> to go the other region and
<c-a>n until you get one region with Vim and the other with R.
- When you have finished to use Vim and R close them and type exit to
quit the screen session.
Here are several useful screen shortcuts:
<c-a><tab> go from Vim to R and vice-versa
<c-a>:resize N set the height of the current window to N lines
<c-a>n switch to the next screen session
<c-a>p switch to the previous screen session
<c-a>S split the current region in two new ones
<c-a>X kill the current region
By default, screen waits briefly after it receives external commands and
other default options may not be what you want. Please read screen
documentation to know how to configure it. Below is a sample ~/.screenrc you
may consider as a starting point to create your own:
7.15. Integration with Conque Shell plugin
The Conque Shell plugin is available at:
By default, the Conque Shell plugin will be used if installed, unless you have
vimrplugin_screenplugin = 1 in your vimrc. If you installed the Conque
Shell but don't want to use it with the Vim-R-plugin, then you should put in
By default, the window will be split horizontally. Put the following in your
vimrc if you prefer to split the window vertically:
Note: Nico Raffo's Conque Shell plugin is not perfect yet, but its use already
has some advantages: the ability to edit R's output, and the syntax
highlighting of the output. The three main problems of Conque Shell are due to
Vim limitations: the lack of a feature that may be called InsertCharPre event,
the impossibility of scrolling a buffer which is not being edited, and the use
of the same variable, 'updatetime', to do both save swap files and trigger
As a consequence of the first limitation, Conque Shell sometimes gets confused
while converting typed text to strings to be sent to the application running
in a Vim buffer. With the current version of Conque Shell (2.0), on Windows,
only ascii characters can be either sent to or typed in the Conque Term. On
Linux or other system whose encoding is UTF-8, characters of any encoding can
be sent to the Conque Term, but only Latin-1 characters can be typed directly
in the Conque Term.
The second limitation has a more obvious consequence: the shell buffer does
not scroll when there is new output but it is not the currently active buffer.
After a command is sent to the Conque buffer, the Conque Shell plugin waits
100 milliseconds (on Linux) or 200 milliseconds (on Windows) before reading
R's output. Longer values for the waiting time will increase the chances that
the output of R commands will be immediately shown in the R Console. To set a
different waiting time, change the value of vimrplugin_conquesleep in your
vimrc as in the example:
To manually scroll the R Console buffer, put the following in your vimrc
(replace <F5> with your preferred key):
Then, you will be able to scroll the R Console buffer at any time by pressing the
<F5> key in Normal mode. Of course, you should replace <F5> with your
You may also want to put the following Conque options in your vimrc (look at
the Conque Shell documentations for details):
Note: The use of ConqueTerm_ReadUnfocused will set the value of 'updatetime'
to 1000 milliseconds.
7.16. Integration with Apple Script (OS X only)
In Mac OS X, the plugin will try to send commands to R gui using Apple Script
if the Screen plugin and the Conque Shell plugin are not installed. If you
prefer to have R running in an external terminal emulator, put in your
7.17. Special R functions
The R function args() list the arguments of a function, but not the arguments
of its methods. If you want that the plugin calls the function
.vim.list.args() after <LocalLeader>ra, you have to add to your vimrc:
By default, R makes a scatterplot of numeric vectors. The function .vim.plot()
do both a histogram and a boxplot. The function can be called by the plugin
after <LocalLeader>rg if you put the following line in your vimrc:
You can set the argument maxdeparse to be passed to R's source() function.
7.19. LaTeX command
By default, Vim calls pdflatex to produce a pdf document from the .tex file
produced by the R Sweave command. You can use the option vimrplugin_latexcmd
to change this behavior. Example:
7.20. Never unmake the R menu and tool bar buttons
Use this option if you want that the menu item R and the R related tool bar
buttons are not deleted when you change from one buffer to another, for
example, when go from an .R file to a .txt one:
When this options is enabled all menu items are created regardless of the file
7.21. Map 'r'
Some users may already be familiar with the key bindings from earlier releases
of the Vim-R-plugin. If the variable vimrplugin_map_r exists, the plugin
will map the letter 'r' to send lines to R when there are visually selected
lines, for compatibility with the original plugin. To activate this option,
insert the following into vimrc:
You may want to add the following three lines to your vimrc which were in
the original plugin and will increase compatibility with code edited with
8. Custom key bindings
When creating custom key bindings for the Vim-R-plugin, it is necessary to
create three maps for most functions because the way the function is called is
different in each Vim mode. Thus, key bindings must be made for Normal mode,
insert mode, and visual mode.
To customize a key binding you should put in your vimrc something like:
The above example shows how you can increase compatibility with old versions
of the Vim-R-plugin, by changing the key binding used to start R from
<LocalLeader>rf to the old default value, F2.
Only the custom key bindings for Normal mode are shown in Vim's menu, but you
can type :map to see the complete list of current mappings, and below is the
list of the names for custom key bindings:
The plugin also contains a function called RAction which allows you to build
ad-hoc commands to R. This function takes the name of an R function such as
"levels" or "table" and the word under the cursor, and passes them to R as a
For example, if your cursor is sitting on top of the object called gender and
you call the RAction function, with an argument such as levels, Vim will pass
the command levels(gender) to R, which will show you the levels of the object
To make it even easier to use this function, you could write a custom key
binding that would allow you to rapidly get the levels of the object under
your cursor. Add the following to your vimrc to have an easy way to pass R
the levels command.
then (assuming that the leader key is "\") if you type \rk R will receive the
You should replace <LocalLeader>rk with the key binding that you want to use
and "levels" with the R function that you want to call.
The following files are part of the plugin and should be in your ~/.vim
directory after the installation:
8 directories, 39 files
10. FAQ and tips
10.1. Is it possible to stop R from within Vim?
Sorry, it is not possible. You have to press ^C into R's terminal emulator.
10.2. Html help and custom pager
If you prefer to see help pages in a html browser, put in your ~/.Rprofile:
and in your vimrc (see vimrplugin_vimpager):
10.3. How do marked blocks work?
Vim allows several marks (bookmarks). The most commonly used marks are the
lowercase alphabet letters. If the cursor is between any two marks, the
plugin will send all of the lines between them to R.
To make it easier to remember where blocks begin and end, we recommended that
you use the ShowMarks plugin available at:
This plugin makes it possible to visually manage your marks. You may want to
add the following two lines to your vimrc to customize ShowMarks behavior:
10.4. Use snipMate
You probably will want to use the snipMate plugin to insert snippets of code
in your R script. The plugin may be downloaded from:
The snipMate plugin does not come with snippets for R, but you can copy the
r.snippets that ships with the Vim-R-plugin (look at the r-plugin directory)
to the snippets directory. The file has only a few snippets, but it will help
you to get started. If you usually edit rnoweb files, you may also want to
create an rnoweb.snippet by concatenating both tex.snippets and r.snippets.
10.5. Easier key bindings for most used commands
The most used commands from Vim-R-plugin probably are "Send line" and "Send
selection". You may find it a good idea to map them to the space bar in your
vimrc (suggestion made by Iago Mosqueira):
You may also want to remap <C-x><C-o>:
10.6. Remap the <LocalLeader>
People writing Rnoweb documents may find it better to use a comma or other key
as the <LocalLeader> instead of the default backslash (see maplocalleader):
10.7. Use a tags file to jump to function definitions
Vim can jump to a function definition if it finds a "tags" file with the
information about the place where the function is defined. To generate the
tags file, use the R function rtags(), which will build an Emacs tags file.
If Vim was compiled with the feature emacs_tags, it will be able to read the
tags file. Otherwise, you can use the function etags2ctags() from the script
located at ~/.vim/r-plugin/etags2ctags.R to convert the Emacs tags file into a
Vim's one. To jump to a function definition, put the cursor over the function
name and hit CTRL-]. Please, read tagsrch.txt for details on how to use tags
files, specially the section tags-option.
You could, for example, download and unpack R's source code, start R inside
the ~/.vim directory and do the following command:
Then, you would quit R and do the following command in the terminal emulator:
Finally, you would put the following in your vimrc, inside an autocmd-group:
Note: While defining the autocmd, the RTAGS path must be put before RsrcTags.
Example on how to test whether your setup is ok:
1. Type "mapply()" in an R script and save the buffer.
2. Press CTRL-] over "mapply" (Vim should jump to "mapply.R").
4. Locate the string "do_mapply", which is the name of a C function.
5. Press CTRL-] over "do_mapply" (Vim sould jump to "mapply.c").
10.8. Fold setup
Vim has several methods of folding text (see fold-methods and
fold-commands). To enable the syntax method of folding for R files, put in
With the above option, Vim will load R files with all folds closed. If you
prefer to start editing files with all folds open, put in your vimrc:
Notes: (1) Enabling folding may slow down Vim. (2) Folding is not a file type
plugin option. It is a feature defined in syntax/r.vim.
10.9. Automatically comment/uncomment code
There are several plugins that make it easy to comment and uncomment code
(respectively, put and remove the '#' symbol from the begin of lines). One of
them is the EnhancedCommentify which allows us to comment/uncomment a line or
a block of lines with the command <Leader>x:
10.9. Run your Makefile from within R
Do you have many Rnoweb files included in a master tex or Rnoweb file and use
a Makefile to build the pdf? You may consider it useful to put the following
line in your vimrc:
10.10. Group windows with compiz
If you are using Compiz, it may be easier to work with the plugin if the
various related windows (editor, terminal, and graphics window) are grouped
because they will be raised together when one of them receives the focus. You
may need CompizConfig Settings Manager installed to enable this feature (look
at the "Window Management" section for "Group and Tab Windows").
10.11. Why do I have to updated the Object Browser manually?
It is because Vim and R run as separate processes and, thus, it is not
possible to Vim to know whether R is busy or not. If R was running as part of
the text editor, as happens with JGR and RKward, which are linked to libR.so,
it would be possible to wait for R to finish processing a command before
sending to it a command to rebuild the list of objects for the Object Browser.
This command should be sent after each line sent to R. But if the
Vim-R-plugin did this, the use of Vim would be blocked until R finished its
10.12. Edit your ~/.Rprofile
You may want to edit your ~/.Rprofile. Two common options are the use of GVim
as the text editor and the use of html help. Example for Linux:
and for Windows:
* Renamed the function SendCmdToScreen to SendCmdToR.
* Clear the current line in the R console before sending a new line.
* Always starts R on the script's directory.
* Don't send "^@$" as part of a paragraph in rnoweb files (thanks to Fabio
Correa for reporting the bug).
* More useful warning message when PyWin32 isn't installed.
* Initial support to Apple Script on Mac OS X (thanks to Vincent Nijs for
writing and testing the code).
* Fix for when whoami returns domain name on Windows (thanks to "Si" for
fixing the bug).
* New command: :RUpdateObjListAll.
* New option: vimrplugin_allnames.
* Allow the use of Python 3.1 on Windows.
* Minor improvements in indentation of R code.
* The file r-plugin/omni_list was renamed to r-plugin/omniList because its
field separator changed to ";".
* Fixed bug that was causing ^H to be exhibited in the R documentation in
some systems. (Thanks to Helge Liebert for reporting the problem).
* New feature: complete chunk block when '<' is pressed in rnoweb files.
* New option: vimrplugin_rnowebchunk.
* New key bindings in Normal mode for Rnoweb files: gn (go to next R code
chunk) and gN (go to previous R code chunk).
* New command: :RBuildTags.
* Added fold capability to syntax/r.vim.
* Improved indentation of rnoweb files: thanks to Johannes Tanzler for
writing the tex.vim indent script and for permitting its inclusion in the
* R CMD BATCH now is called with --no-restore --no-save (key binding \ro).
* The file r-plugin/omnilist now has an additional field and was renamed as
* Use 64 bit version of R by default on Windows if the directory bin/x64
* New Windows only option: vimrplugin_i386.
* New option: vimrplugin_routmorecolors.
* Fixed bug in the Object Browser when a data.frame or list had just one
element (thanks to Jan Larres for reporting the bug).
* Do not copy omnilist and functions.vim to ~/.vim/r-plugin if the directory
where the plugin is installed is writable (thanks to Jan Larres for the
* New options: vimrplugin_objbr_place and vimrplugin_objbr_w.
* New default value: vimrplugin_vimpager = "vertical"
* The R help can now be seen in a Vim buffer on MS Windows.
* Fix width of help text when R version >= 2.12.0.
* Implemented actions in the Object Browser: summary, print, etc...
* Browse libraries objects in Object Browser.
* Minor bug fixes in the Object Browser.
* New feature: Object Browser.
* Conque Shell will be used if installed unless explicitly told otherwise in
* New valid value for vimrplugin_vimpager: "tabnew"
* New option: vimrplugin_vimpager.
* Do not let Vim translate "File" in R menu.
* Fixed bug when the option vimrplugin_r_path was used (thanks to Asis Hallab
for reporting the bug),
* Fixed bug (E687) when user created custom key binding (thanks to Philippe
Glaziou for reporting the bug).
* Changed the use of vimrplugin_r_path: now the option includes only the
directory part of the path.
* Initial support to Conque Shell plugin. Thanks to "il_principe orange" for
suggesting the use of Conque Shell, "ZyX-I" for writing the initial code to
use Conque Shell, and Nico Raffo for writing the plugin and additional code
to integrate both plugins.
* New options: vimrplugin_conqueplugin and vimrplugin_conquevsplit.
* New option: vimrplugin_r_args.
* Fixed bug when the plugin was installed in a directory other than ~/.vim
(thanks to Tom Link).
* Initial support for Vim-R communication on Windows using Python.
* Minor improvements in syntax highlighting.
* New option: vimrplugin_buildwait.
* New option: vimrplugin_r_path (thanks to Asis Hallab).
* Fixed bug in .Rsource name making in some systems.
* Dropped options vimrplugin_hstart and vimrplugin_browser_time.
* If ~/.vim/r-plugin/functions.vim is not found, try to copy it from
* Minor bug fixes.
* Added menu item and key binding for run "R CMD BATCH" and open the
resulting ".Rout" file.
* Fixed bug when more than one Vim instance used the same file to send
multiple lines of code to R (thanks to Bart for reporting the bug).
* Adapted the plugin to allow the creation of a Debian package.
* Added options vimrplugin_listmethods and vimrplugin_specialplot.
* Improved syntax highlight of R batch output (.Rout files).
* No longer uses the external programs grep, awk and sed to build the
additional syntax file containing the list of functions.
* Fixed :RUpdateObjList bug when list had length 0.
* Fixed 'E329: No menu "R"' when more than one file were loaded simultaneously
by calling vim with either -p or -o parameters. Thanks to Peng Yu for
reporting the bug.
* Correctly recognize a newly created file with extension ".R" as an R script
* Replaced "-t" with "--title" to make xfce4-terminal work again.
* Thanks to Tortonesi Mauro who wrote a patch to make the plugin work with
* Added simple syntax hightlight for .Rout files.
* Increased the time limit of RUpdateObjList to two minutes.
* Improvement in the syntax highlight based on code written by Zhuojun Chen.
* Thanks to Scott Kostyshak who helped to improve the documentation.
* Iago Mosqueira suggested that the plugin should be able to run one R process
for each Vim instance, and his suggestion was implemented with the option
* Syntax highlight for R functions.
* Added "info" field to omni completion (thanks to Ben Kujala for writing the
* The plugin now can run together with screen.vim, thanks to Eric Van
Dewoestine, the author of screen.vim, who added script integration to
* Andy Choens has made many improvements on the documentation.
* Added the possibility of custom key binding creation to call any R function
with the word under cursor as argument.
* The key bindings related with Sweave are activated even if the file type is
* Replaced <Leader> with <LocalLeader> in the key bindings.
* Added "Send Paragraph" commands.
* Jose Claudio Faria has begun to work in the project as co-author.
* Some ideas from Tinn-R project were ported to the plugin.
* The main menu has new items and the toolbar new icons.
* Documentation improvements.
* Faster startup.
* Better support for Rnoweb files: the cursor goes to '^<<' if the sent line
* Now use screen instead of funnel.pl. The bugs and limitations related with
funnel.pl are solved.
* Deleted key binding for R-devel.
* Automatically detect available terminal emulators and choose one of them.
* By default, no longer calls help.start() the first time that CTRL-H is
* Added R icons for some terminal emulators.
* Removed the script open-gvim-here. You may use Vim's option autochdir.
* Added option vimrplugin_term.
* Improved indentation script.
* Changed key binding from Shift-Enter, which doesn't work in any terminal, to
Alt-Enter, which at least works in xterm.
* The options expandtab, shiftwidth and tabstop are no longer set by the plugin.
* Better word detection before calling R's help().
* Fixed bug in underscore replacement.
* Fixed small bug in code indentation.
* Added scipt rpager.sh.
* Added two new plugin options: no underscore replacement and fixed name for
the pipe file instead of random one.
* Key bindings now are customizable.
* Default key binding for calling R's args() changed to Shift-F1.
* New R script rargs.R gives better results for generic functions than R's
args() called directly.
* Don't send large blocks of code to R to avoid xterm freezing.
* Automatically call help.start() after CTRL-H is pressed for the first time,
and wait 4 seconds for the browser start before calling R's help(). These
features are customizable.
* Fixed tags file script.
* Added documentation.
* Added ability to send function to R, revert the automatic conversion of "_"
into "<-" and call R's help().
* Added archive with some files to ease desktop integration, if desired.
* Initial upload