Tight integration between vim and R. I am not the original author of this plugin I just want to improve it's mac os x support. For support: please email: jalvesaq@gmail.com or joseclaudio.faria@gmail.com
Vim script R Shell
Switch branches/tags
Nothing to show
Clone or download
Pull request Compare This branch is even with jimmyharris:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


*r-plugin.txt*                                                  *vim-r-plugin*

                            Plugin to work with R~

Authors: Jakson A. Aquino   <jalvesaq@gmail.com>
         José Cláudio Faria <joseclaudio.faria@gmail.com>

Version: 100521

For Vim version 7.2 and above

 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-custom-key-bindings|
 9. Files                                       |r-plugin-files|
10. FAQ and tips                                |r-plugin-faq|
11. News                                        |r-plugin-news|

1. Overview~

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) and some ideas from the Tinn-R (Windows only)

The latest version of this plugin is available at:


Constructive 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.

2. Main features~

2.1. Linux/Unix only:~

  * Integrated communication with R;
  * Omni completion (auto-completion) for R objects.

2.2. All platforms:~

  * Syntax highlighting for R syntax;
  * Smart indentation for R syntax.

3. Installation~

3.1. Dependencies~

This plugin requires users to install two external dependencies. Before using
this plugin, you must install:

    * screen - http://www.gnu.org/software/screen/
    * R-Project - http://www.r-project.org/

This software is already packaged for most GNU/Linux distributions and other
Unix variants. In fact, screen is installed by default on many Linux 

Unfortunately, installation instructions for these dependencies vary widely
and are beyond the scope of this documentation. Please review the installation
instructions for your operating system for these external dependencies.

3.2. General instructions~

You need to activate plugins and indentation according to 'filetype' in your
  filetype plugin indent on
Create your ~/.vim directory if you do not have it yet:
  mkdir -p ~/.vim
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.

Uncompress the archive:
  tar -xvzf vim-r-plugin2-*.tar.gz -C ~/.vim
Start Vim and build the tags file for this document (and others that eventually
are in at the same directory):
  :helptags ~/.vim/doc
Update the list of objects for omni completion and syntax highlight (see
|:RUpdateObjList| for details).

3.3. Optional step~

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:


4. Use~

4.1 Key bindings~

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' variable (see |<LocalLeader>|)

  . 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
  . 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
  . Paragraph                              \pp
  . Paragraph (echo)                       \pe
  . Paragraph (and down)                   \pd
  . Paragraph (echo and down)              \pa
  . Selection                              \ss
  . Selection (echo)                       \se
  . Selection (and down)                   \sd
  . Selection (echo and down)              \sa
  . 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
  . Set working directory (cur file path)  \rd
  . Sweave (cur file)                      \sw
  . Sweave and PDF (cur file)              \sp
  . Rebuild (list of objects)              \ro

  . 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.

The key bindings \sw and \sp are useful only if the file type is rnoweb
(.Rnw). When the cursor is over the @ character that 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.

Please see |r-plugin-custom-key-bindings| to learn how to customize the key
bindings without editing the plugin directly, and |g:vimrplugin_underscore| to
to disable underscore replacement.

4.2 Syntax highlight and omni completion~
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 tags file for omni completion including all
objects currently in R's workspace, with the exception of the .GlobalEnv
objects. These two lists are stored permanently in the ~/.vim/tools directory.
If you prefer to not have the functions highlighted, delete the file

5. How the plugin works~

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.

5.1. Communication through screen~

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 |g:vimrplugin_single_r|.

5.2. 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.

You can build/rebuild the tags file at any time. Remember, you must rebuild
the tags file manually to add the names of other objects created after
building the tags file.

If a data.frame is found, while building the tags file, the columns in the
data.frame are added to the list of objects. 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 tags file used for omni completion is built by the R function contained in
the script ~/.vim/tools/rtags.R. This function is sourced by R, which causes R
to create the tags file used by Vim.

Vim uses two tags files: one for the objects of .GlobalEnv and the other for
all other objects. The .GlobalEnv tags file is stored in the /tmp directory
and, thus, is deleted after each reboot. The other tags file is stored in
~/.vim/tools and remains available until you manually rebuild it with the
command: |:RUpdateObjList|.

6. Known bugs and workarounds~

6.1. R session is detached when GVim is closed~

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:
  screen -r

6.2. Indentation~

Correctly written code might be wrongly indented. Examples:

   this code                               is indented as:~
   if(T)                                   if(T)
     for(i in 1:2)                           for(i in 1:2)
     {                                     {
       cat(i, "\n")                          cat(i, "\n")
     }                                     }
   if(T){                                  if(T){
     if(T)                                   if(T)
     {                                       {
       cat("something\n")                      cat("something\n")
   }}                                        }}

6.3 R's source() issues~

The R's source() function prints an extra new line between commands if the
option echo = TRUE, and error messages are printed only after the function has
finished, which make it more difficult to find errors in the code sent to R.

6.4 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 and, consequently, the plugin unmakes the toolbar buttons and
R related menu items. 

7. Options~

7.1. Terminal emulator~

The plugin uses the first terminal emulator that it finds in the following
    1. gnome-terminal, 
    2. konsole, 
    3. xfce4-terminal, 
    4. Eterm, 
    5. rxvt, 
    6. aterm, 
    7. xterm.

If Vim does not select your favorite terminal emulator, you may define it in 
your |vimrc| by setting the variable g:vimrplugin_term, as shown below:
  let g:vimrplugin_term = "xterm"
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 g:vimrplugin_term_cmd, as in the example below:
  let g:vimrplugin_term_cmd = "gnome-terminal -t R -e"

7.2. Underscore~
To disable the underscore replacement with " <- " put the following in your
  let g:vimrplugin_underscore = 1

7.3. Pager~
You may also want to use less in a separate terminal emulator as the default
pager for R's help. You can use the script ~/.vim/tools/rpager.sh (which will
call less) by putting in your ~/.Rprofile:

This script can be easily modified to use your favorite terminal emulator. The
script contains options for several popular emulators such as gnome-terminal
and konsole but defaults to xterm.

7.4. Html help~
The plugin can call R's function help.start() the first time that you press
CTRL-H. If you want this behavior, you should put in your |vimrc|:
  let g:vimrplugin_hstart = 1
After calling help.start(), the plugin will wait 4 seconds before sending to R
the help command. If your browser needs either more or less time to start, you
may want to add the following global variable (with the appropriate value) to
your |vimrc|:
  let g:vimrplugin_browser_time = 4

7.5. Number of R processes~
If you prefer that each Vim buffer uses its own R process, put the following
option in your |vimrc|:
  let g:vimrplugin_nosingler = 1
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|:
  let g:vimrplugin_by_vim_instance = 1
This is the default behavior when using Vim with the screen.vim plugin, and,
thus, there is no need to use this option if already running Vim with the
option |g:vimrplugin_screenplugin|(see below). The
|g: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.6. Screen configuration~
Vim runs screen with a special configuration file. If you want to use
your own ~/.screenrc, put in your |vimrc|:
  let g:vimrplugin_noscreenrc = 1

7.7. Integration with screen.vim~
By default, the r-plugin does not use the screen.vim plugin, written by Eric
Van Dewoestine. If you prefer to use both plugins at the same time, download
and install the screen.vim (version 0.8 or above) from:


Using both plugins at the same time is especially useful for users who may
prefer to use Vim and R from the command-line, rather than using the graphical
interface provided by GVim.

To integrate the r-plugin with screen.vim you will need to add the following 
to your |vimrc|:
  let g:vimrplugin_screenplugin = 1
Note: Read the screen.vim description at plugin/screen.vim, especially the
section "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:
      screen -r
  - 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:
  msgwait 0
  termcapinfo xterm* 'ti@:te@'
  vbell off
  term screen-256color

7.8. Map 'r'~
Some users may already be familiar with the key bindings from earlier releases
of the r-plugin. If the variable g: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|:
  let g:vimrplugin_map_r = 1
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
  set expandtab
  set shiftwidth=4
  set tabstop=8

7.9. maxdeparse~
You can set the argument maxdeparse to be passed to R's source() function.
  let g:vimrplugin_maxdeparse = 300

7.10. 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 g:vimrplugin_latexcmd
to change this behavior. Example:
  let g:vimrplugin_latexcmd = "latex"

8. Custom key bindings~
When creating custom key bindings for the 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:
  map <F2> <Plug>RStart
  imap <F2> <Plug>RStart
  vmap <F2> <Plug>RStart
The above example shows how you can increase compatibility with old versions
of the r-plugin, by changing the key binding used to start R from
<LocalLeader>rf to the old default value, F2.

Custom key bindings are not shown in Vim's menu, but you can type |:map| to 
see the list of current mappings, and below is the list of the names for 
custom key bindings:
  RBuildTags             RESendSelection           RSendLine
  RClearAll              RHelp                     RSendMBlock
  RClearConsole          RListSpace                RSendSelection
  RClose                 RMakePDF                  RSetwd
  RCustomStart           RObjectNames              RShowArgs
  RDSendFunction         RObjectPr                 RShowEx
  RDSendLine             RObjectStr                RSPlot
  RDSendSelection        RPlot                     RStart
  REDSendMBlock          RSaveClose                RStop
  REDSendSelection       RSendFile                 RSummary
  RESendFile             RSendFunction             RSweave
  RESendMBlock           RSendLAndOpenNewOne       RvanillaStart
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.
  map <Leader>rk :call RAction("levels")<CR>
then (assuming that the leader key is "\") if you type \rk R will receive the
You should replace <Leader>rk with the key binding that you want to use and
"levels" with the R function that you want to call.

9. Files~
The following files are part of the plugin and should be in your ~/.vim
directory after the installation:

   |-- after
   |   |-- filetype.vim
   |   `-- syntax
   |       `-- r.vim
   |-- autoload
   |   `-- rcomplete.vim
   |-- bitmaps
   |   |-- r-close.xpm 
   |   |-- r-control-clear.png 
   |   |-- r-control-clearall.png
   |   |-- r-control-listspace.png
   |   |-- r-send-block.png
   |   |-- r-send-file.png
   |   |-- r-send-function.png
   |   |-- r-send-line.png
   |   |-- r-send-selection.png
   |   `-- r-start.xpm
   |-- doc
   |   `-- r-plugin.txt
   |-- ftplugin
   |   |-- r.vim
   |   |-- rhelp.vim -> r.vim
   |   `-- rnoweb.vim -> r.vim
   |-- indent
   |   `-- r.vim
   `-- tools
       |-- rargs.R
       |-- rpager.sh
       `-- rtags.R

10. FAQ and tips~

10.1. How can I make the plugin active for all file types?~
  If you want to make most of the plugin functions available for any file
  type, create a symbolic link to ftplugin/r.vim in the plugin directory. For
  example, if you installed the plugin in your home directory do the following
  commands in a terminal emulator:
  cd ~/.vim/plugin
  ln -s ../ftplugin/r.vim

10.2. How do marked blocks work?~
  Vim allows several marks (bookmarks). The most commonly used marks are |a..z|.
  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 
  let marksCloseWhenSelected = 0
  let showmarks_include = "abcdefghijklmnopqrstuvwxyz"

10.3. 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.4. 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):
  vmap <Space> <Plug>RDSendSelection
  nmap <Space> <Plug>RDSendLine

10.5 Use "," as local map leader~
  People writing Rnoweb documents may find it better to use a comma as local
  leader instead of the default backslash:
  let maplocalleader = ","

10.6 Run your Makefile from within R~
  Do you have many Rnoweb files included in a master tex or Rnoweb file and
  uses a Makefile to build the pdf? You may consider it useful to put the
  following line in your |vimrc|:
  nmap <LocalLeader>sm :update<CR>:call SendCmdToScreen('system("make")')<CR>

10.7 Group windows with 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").

11. News~
100521 (2010-05-12)

* Replaced "-t" with "--title" to make xfce4-terminal work again.

100512 (2010-05-12)

* 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

091223 (2009-12-23)

* Syntax highlight for R functions.
* Added "info" field to omni completion (thanks to Ben Kujala for writing the
  original code).

091016 (2009-10-16)
* 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
  not rnoweb.
* Replaced <Leader> with <LocalLeader> in the key bindings.
* Added "Send Paragraph" commands.

091004 (2009-10-04)
* José Cláudio Faria has began 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.

090828 (2009-08-28)
* Faster startup.
* Better support for Rnoweb files: the cursor goes to '^<<' if the sent line
  is '^@$'.

090811 (2009-08-12)
* 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

090810 (2009-08-10)
* Added R icons for some terminal emulators.
* Removed the script open-gvim-here. You may use Vim's option autochdir.
* Added option g: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.

090610 (2009-06-11)
* 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.

090523 (2009-05-23)
* 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.

090519 (2009-05-20)
* 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.

090516 (2009-05-16)
* 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.

090507 (2009-05-08)
* Initial upload