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

Authors: Jakson A. Aquino <[email protected]>

Jose Claudio Faria <[email protected]>

Version: 1.2.7

For Vim version 7.4

1. Overview |r-plugin-overview|

2. Main features |r-plugin-features|

3. Installation |r-plugin-installation|

4. Use |r-plugin-use|

5. Known bugs and workarounds |r-plugin-known-bugs|

6. Options |r-plugin-options|

7. Custom key bindings |r-plugin-key-bindings|

8. License and files |r-plugin-files|

9. FAQ and tips |r-plugin-tips|

10. News |r-plugin-news|

*r-plugin-overview*

This plugin improves Vim's support for editing R code and makes it possible to

integrate Vim with R. If you want to use Neovim and R, see:

https://github.com/jalvesaq/Nvim-R

The plugin uses some ideas and code from Johannes Ranke's (vim-r-plugin), Eric

Van Dewoestine's (screen.vim plugin), Vincent Nijs (R.vim for Mac OS X) and

some ideas from the Tinn-R (Windows only) project.

The latest stable version of this plugin is available at:

http://www.vim.org/scripts/script.php?script_id=2628

Feedback is welcomed. Please submit bug reports to the developers. Do not like

a feature? Tell us and we may add an option to disable it. If you have any

comments or questions, please post them at:

https://groups.google.com/forum/#!forum/vim-r-plugin

The plugin should emit useful warnings if you do things it was not programmed

to deal with. Cryptic error message are bugs... Please report them at:

https://github.com/jcfaria/Vim-R-plugin/issues

We do not plan to take the initiative of writing code for new features, but

patches and git pull requests are welcome. If you want a feature that only few

people might be interested in, you can write a script to be sourced by the

Vim-R-plugin (see |vimrplugin_source|).

*r-plugin-features*

* Syntax highlighting for R code, including:

- Special characters in strings.

- Functions of loaded packages.

- Special highlighting for R output (.Rout files).

- Spell check only strings and comments.

- Fold code when foldmethod=syntax.

* Syntax highlighting for RHelp, RMarkdown and RreStructuredText.

* Smart indentation for R, RHelp, Rnoweb, RMarkdown and RreStructuredText.

* 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, knit and pdflatex commands.

* Omni completion (auto-completion) for R objects (.GlobalEnv and loaded

packages).

* Auto-completion of function arguments.

* Auto-completion of knitr chunk options.

* 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

available room).

- Automatic formatting 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):

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

* SyncTeX support.

* Most of the plugin's behavior is customizable.

For screenshots see: http://www.lepem.ufc.br/jaa/vim-r-plugin.html

*r-plugin-installation*

The installation instructions are split in six sections:

3.1. Preliminary system setup on Windows

3.2. Preliminary system setup on Mac OS X

3.3. Preliminary system setup on Unix

3.4. Plugin installation

3.5. Troubleshooting

3.6. Optional steps

Before installing the plugin, you should install several external

dependencies:

* R's version must be >= 3.0.0: http://www.r-project.org/

* vimcom = 1.2-7: http://www.lepem.ufc.br/jaa/vimcom.html

Note: If you cannot build vimcom yourself, you will want to

download and install the zip file.

* Vim's version must be >= 7.4: http://www.vim.org/download.php

* Only if you write Rnoweb code:

* Sumatra PDF viewer >= 3.0.

* MikTeX or other LaTeX distribution.

* Perl (required to run `latexmk`).

Add the following lines to your `Rprofile`:

If you do not know where your .Rprofile is, do the following command in R

Console to open it:

Before installing the plugin, you should install its dependencies:

Cocoa MacVim >= 7.4: https://code.google.com/p/macvim

R >= 3.0.0: http://www.r-project.org/

vimcom = 1.2-7: http://www.lepem.ufc.br/jaa/vimcom.html

Only if you edit Rnoweb files: MacTeX, BasicTeX or other LaTeX system.

If you want to call R.app from MacVim, put in your `~/.Rprofile`:

On Mac OS X, the plugin will use AppleScript to send commands to the R Console

application unless |vimrplugin_applescript| = 0. In this case, R will run in a

external terminal emulator. The advantage of running R in a terminal emulator

is that its output can be colorized by the R package "colorout". If you want

to try this configuration, install Tmux and the R packages "setwidth" and

"colorout" (see instructions in section 3.3) and put in your `~/.Rprofile`:

Note: The plugin is fully functional with MacVim, but the Vim application that

comes with MacVim does not have the the server side of the 'clientserver'

feature which is required to have the plugin working properly. If you want to

run both Vim and R in the same Tmux window in a terminal emulator, you have to

follow the instructions from section 3.3.

Before installing the plugin, you should install its dependencies:

Vim, GVim >= 7.4: http://www.vim.org/download.php

Note: The Vim-R-plugin requires Vim compiled with |+libcall|,

|+clientserver| and |+conceal| features. In Normal mode, do

`:version` to check if your Vim has these features.

If you need to use the Vim-R-plugin in a Unix system without the

X Server running (e.g. Linux Console, and any system accessed

through ssh), the best option is to use Neovim and Nvim-R:

https://github.com/jalvesaq/Nvim-R

If you cannot use Neovim and need to use Vim in these

circumstances, please, read |r-plugin-nox| and |r-plugin-remote|.

R >= 3.0.0: http://www.r-project.org/

vimcom = 1.2-7: http://www.lepem.ufc.br/jaa/vimcom.html

Tmux >= 1.8: http://tmux.sourceforge.net

Tmux is necessary to send commands from Vim to R Console.

wmctrl: http://tomas.styblo.name/wmctrl/

Required for better SyncTeX support under X Server.

colorout: http://www.lepem.ufc.br/jaa/colorout.html

Colorizes the R output.

setwidth: An R package that can be installed with the command

`install.packages("setwidth")`.

The library setwidth adjusts the value of `options("width")`

whenever the terminal is resized.

ncurses-term: http://invisible-island.net/ncurses

Might be necessary if you want support for 256 colors at the

terminal emulator.

latexmk: Automate the compilation of LaTeX documents.

See examples in |vimrplugin_latexcmd|.

Note: Vim, R, Tmux, ncurses-term and latexmk are already packaged for most

GNU/Linux distributions and other Unix variants. Unfortunately their

installation instructions vary widely and are beyond the scope of this

documentation.

Put the following lines in your `~/.Rprofile`:

Put the following in your `~/.bashrc`:

Before proceeding, you have to start a new shell session to have the alias

enabled.

If you start Vim in a terminal emulator, inside of a Tmux session, the plugin

will split the Tmux window in two and start R in the other pane. This is the

recommended way of running the plugin on Linux (read |r-plugin-tmux| for

details). If you either use GVim or Vim not inside a Tmux session the plugin

will start R in a external terminal emulator. This is useful if you have two

monitors.

If you run Vim in a terminal emulator, it must be started with the argument

|--servername| to enable the 'clientserver' feature (please, read the section

|r-plugin-bash-setup| to know some tips on how to configure Bash). This is not

necessary with GVim because it always runs with the 'clientserver' feature

enabled.

You need to activate plugins and indentation according to 'filetype'. You

should have at least the following options at the top or near the very top

of your |vimrc| (but below `set` `runtimepath`, if you have set it):

Download the latest version of the plugin from:

http://www.vim.org/scripts/script.php?script_id=2628

If you either are on Windows or prefer to use a graphical interface, start the

file manager, find the file `Vim-R-plugin.vmb` and open it with GVim or

MacVim. Otherwise, start a terminal emulator, go to the directory where you

have downloaded the plugin and type:

Then, in Vim, type:

Press <Enter> to start the installation and press the <Space> bar as many

times as necessary to finish the installation. You should, then, quit Vim.

Note: If you need to install the plugin in a non default directory, do

`:UseVimball` `[path]`. In this case, the configuration of Vim's 'runtimepath'

must be done before the command "filetype on" in both the system and the user

|vimrc| files, otherwise, some file types might not be correctly recognized.

The plugin is installed and will be activated next time that you start to edit

an R script.

You may want to improve the configuration of your |vimrc| for a better use of

the plugin. Please, see |r-plugin-vimrc-setup|.

If you want to uninstall the plugin, do

Note: The <LocalLeader> is '\' by default.

The plugin is a |file-type| plugin. It will be active only if you are editing

a .R, .Rnw, .Rd, Rmd, or Rrst file. The menu items will not be visible and the

key bindings will not be active while editing either unnamed files or files

with name extensions other than the mentioned above. If the plugin is active,

pressing <LocalLeader>rf should start R.

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.

On Windows, if R does not start and you get an error message instead, you may

want to set the path to your Rgui.exe in your |vimrc|, for example (please

adapt to your installation):

Are you using Debian, Ubuntu or other Debian based Linux distribution? If yes,

you may prefer to install the Debian package available at:

http://www.lepem.ufc.br/jaa/vim-r-plugin.html

Did you see the message "VimCom port not found"? This means that R is not

running, the vimcom package is not installed (or is installed but is not

loaded), or R was not started by Vim.

If R takes more than 5 seconds to load, you should adjust the value of

|vimrplugin_vimcom_wait|.

Please, read the section |r-plugin-options|. Emacs/ESS users should read the

section |r-plugin-indenting| of this document.

You may be interested in installing additional general plugins to get

functionality not provided by this file type plugin. Particularly interesting

are vim-signature, csv.vim and snipMate. Please read |r-plugin-tips| for

details. If you edit Rnoweb files, you may want to try LaTeX-Box for

omnicompletion of LaTeX code (see |r-plugin-latex-box| for details).

*r-plugin-use*

Note: The <LocalLeader> is '\' by default.

Note: It is recommended the use of different keys for <Leader> and

<LocalLeader> to avoid clashes between filetype plugins and general plugins

key binds. See |filetype-plugins|, |maplocalleader| and |r-plugin-localleader|.

To use the plugin, open a .R, .Rnw, .Rd, .Rmd or .Rrst file with Vim and type

<LocalLeader>rf. Then, you will be able to use the plugin key bindings to send

commands to R.

This plugin has many key bindings, which correspond with menu entries. In the

list below, the backslash represents the <LocalLeader>. Not all menu items and

key bindings are enabled in all filetypes supported by the plugin (r, rnoweb,

rhelp, rrst, rmd).

Start/Close

. Start R (default) \rf

. Start R (custom) \rc

--------------------------------------------------------

. Close R (no save) \rq

. Stop R :RStop

Send

. 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

--------------------------------------------------------

. Chunk (cur) \cc

. Chunk (cur, echo) \ce

. Chunk (cur, down) \cd

. Chunk (cur, echo and down) \ca

. Chunk (from first to here) \ch

--------------------------------------------------------

. 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

. Selection (evaluate and insert output in new tab) \so

--------------------------------------------------------

. 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

. Left part of line (cur) \r<Left>

. Right part of line (cur) \r<Right>

. Line (evaluate and insert the output as comment) \o

Command

. List space \rl

. Clear console \rr

. Clear all \rm

--------------------------------------------------------

. Print (cur) \rp

. Names (cur) \rn

. Structure (cur) \rt

. View data.frame (cur) \rv

--------------------------------------------------------

. 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

. Sweave, BibTeX and PDF (cur file) (Linux/Unix) \sb

--------------------------------------------------------

. Knit (cur file) \kn

. Knit and PDF (cur file) \kp

. Knit, BibTeX and PDF (cur file) (Linux/Unix) \kb

. Knit and Beamer PDF (cur file) (only .Rmd) \kl

. Knit and HTML (cur file, verbose) (only .Rmd) \kh

. Spin (cur file) (only .R) \ks

--------------------------------------------------------

. Open PDF (cur file) \op

. Search forward (SyncTeX) \gp

. Go to LaTeX (SyncTeX) \gt

--------------------------------------------------------

. Build tags file (cur dir) :RBuildTags

Edit

. Insert "<-" _

. Complete object name ^X^O

. Complete function arguments ^X^A

--------------------------------------------------------

. Indent (line) ==

. Indent (selected lines) =

. Indent (whole buffer) gg=G

--------------------------------------------------------

. Toggle comment (line, sel) \xx

. Comment (line, sel) \xc

. Uncomment (line, sel) \xu

. Add/Align right comment (line, sel) \;

--------------------------------------------------------

. Go (next R chunk) \gn

. Go (previous R chunk) \gN

Object Browser

. Show/Update \ro

. Expand (all lists) \r=

. Collapse (all lists) \r-

. Toggle (cur) Enter

Help (plugin)

Help (R) :Rhelp

Please see |r-plugin-key-bindings| to learn how to customize the key bindings

without editing the plugin directly.

The plugin commands that send code to R Console are the most commonly used. If

the code to be sent to R has a single line it is sent directly to R Console,

but if it has more than one line (a selection of lines, a block of lines

between two marks, a paragraph etc) the lines are written to a file and the

plugin sends to R the command to source the file. To send to R Console the

line currently under the cursor you should type <LocalLeader>d. If you want to

see what lines are being sourced when sending a selection of lines, you can

use either <LocalLeader>se or <LocalLeader>sa instead of <LocalLeader>ss.

The command <LocalLeader>o runs in the background the R command `print(line)`,

where `line` is the line under cursor, and adds the output as commented lines

to the source code.

If the cursor is over the header of an R chunk with the `child` option (from

Rnoweb, RMarkdown or RreStructuredText document), and you use one of the

commands that send a single line of code to R, then the plugin will send to R

the command to knit the child document.

After the send, sweave and knit commands, Vim will save the current buffer if

it has any pending changes before performing the tasks. After <LocalLeader>ao,

Vim will 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

<LocalLeader>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. The replacement will always happen if

syntax highlighting is off (see |:syn-on| and |:syn-off|). 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. You have to change the value of

|vimrplugin_assign| to disable underscore replacement.

When you press <LocalLeader>rh, the plugin shows the help for the function

under the cursor. The plugin also checks the class of the object passed as

argument to the function to try to figure out whether the function is a

generic one and whether it is more appropriate to show a specific method. The

same procedure is followed with <LocalLeader>rp, that is, while printing an

object. For example, if you run the code below and, then, press

<LocalLeader>rh and <LocalLeader>rp over the two occurrences of `summary`, the

plugin will show different help documents and print different function methods

in each case:

If the object under the cursor is a data.frame or a matrix, <LocalLeader>rv

will show it in a new tab. If the csv.vim plugin is not installed, the

Vim-R-plugin will warn you about that (see |r-plugin-df-view|). Specially

useful commands from the csv.vim plugin are |:CSVHeader|, |:ArrangeColumn| and

|:CSVHiColumn|. It can be installed from:

http://www.vim.org/scripts/script.php?script_id=2830

When completing object names (CTRL-X CTRL-O) and function arguments (CTRL-X

CTRL-A) you have to press CTRL-N to go foward in the list and CTRL-P to go

backward (see |popupmenu-completion|). Note: if using Vim in a terminal

emulator, Tmux will capture the CTRL-A command. You have to do CTRL-A twice to

pass a single CTRL-A to Vim. For rnoweb, rmd and rrst file types, CTRL-X

CTRL-A can also be used to complete knitr chunk options if the cursor is

inside the chunk header.

If R is not running or if it is running but is busy the completion will be

based on information from the packages listed by |vimrplugin_start_libs|

(provided that the libraries were loaded at least once during a session of

Vim-R-plugin usage). Otherwise, the pop up menu for completion of function

arguments will include an additional line with the name of the library where

the function is (if the function name can be found in more than one library)

and the function method (if what is being shown are the arguments of a method

and not of the function itself). For library() and require(), when completing

the first argument, the popup list shows the names of installed packages, but

only if R is running.

To get help on an R topic, type in Vim (Normal mode):

The command may be abbreviated to :Rh and you can either press <Tab> to

trigger the autocompletion of R objects names or hit CTRL-D to list the

possible completions (see |cmdline-completion| for details on the various ways

of getting command-line completion). The list of objects used for

completion is the same available for omnicompletion (see

|vimrplugin_start_libs|). You may close the R documentation buffer by

simply pressing `q`.

You can source all .R files in a directory with the Normal mode command

:RSourceDir, which accepts an optional argument (the directory to be sourced).

*:Rinsert*

The command :Rinsert <cmd> inserts one or more lines with the output of the

R command sent to R. By using this command we can avoid the need of copying

and pasting the output R from its console to Vim. For example, to insert the

output of `dput(levels(var))`, where `var` is a factor vector, we could do in

Vim:

The output inserted by :Rinsert is limited to 5012 characters.

The command :Rformat calls the function `tidy_source()` of formatR package

to format either the entire buffer or the selected lines. The value of the

`width.cutoff` argument is set to the buffer's 'textwidth' if it is not

outside the range 20-180. Se R help on `tidy_source` for details on how to

control the function behavior.

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

mode:

[count]<LocalLeader>gn : go to the next chunk of R code

[count]<LocalLeader>gN : go to the previous chunk of R code

The commands <LocalLeader>cc, ce, cd and ca send the current chunk of R code

to R Console. The command <LocalLeader>ch sends the R code from the first

chunk up to the current line.

The commands <LocalLeader>kn builds the .tex file from the Rnoweb one using

the knitr package and <LocalLeader>kp compiles the pdf; for Sweave, the

commands are, respectively <LocalLeader>sw and <LocalLeader>sp. On Linux, if

using Evince, Okular or Zathura, you can jump from the Rnoweb file to the PDF

with the command <LocalLeader>gp. To jump from a specific location in the PDF

to the corresponding line in the Rnoweb, in either Evince or Zathura you

should press <C-LeftMouse>, and in Okular <S-LeftMouse>. No configuration is

required if you use Evince, Gnome-Terminal and the knitr package, and work

with single file Rnoweb documents. Otherwise, see |r-plugin-SyncTeX| for

configuration details.

The plugin adds some features to the default syntax highlight of R code. One

such feature is the highlight of R functions. However, functions are

highlighted only if their libraries are loaded by R (but see

|vimrplugin_start_libs|).

Note: If you have too many loaded packages Vim may be unable to load the list

of functions for syntax highlight.

Vim can automatically complete the names of R objects when CTRL-X CTRL-O is

pressed in insert mode (see |omni-completion| for details). 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, the plugin

can also show the function arguments in a separate preview window (this

feature is disabled by default: see |vimrplugin_show_args|).

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.

Only the names of objects in .GlobalEnv and in loaded libraries are completed,

and the |clientserver| feature is required to get the list of loaded libraries

automatically updated. If either R is not running or Vim is running without

the |clientserver| feature, only objects of libraries listed in

|vimrplugin_start_libs| will have their names completed. When you load a new

library in R, only the current buffer has the highlighting of function names

immediately updated. If you have other buffers open, they will be updated when

you enter them.

Vim uses one file to store the names of .GlobalEnv objects and a list of files

for all other objects. The .GlobalEnv list is stored in the `$VIMRPLUGIN_TMPDIR`

directory and is deleted when you quits Vim. The other files are stored in the

`$VIMRPLUGIN_COMPLDIR` directory and remain available until you manually delete

them.

You have to use <LocalLeader>ro to start the Object Browser. The Object

Browser has two views: .GlobalEnv and Libraries. If you either press <Enter>

or double click (GVim or Vim with 'mouse' set to "a") on the first line of the

Object Browser, you will toggle the view between the objects in .GlobalEnv and

the currently loaded libraries. The Object Browser requires the

|+clientserver| feature to be automatically updated and the |+conceal| feature

to correctly align list items.

In the .GlobalEnv view, if an object has the attribute "label", it will also

be displayed. 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 R in an environment where the string UTF-8 is part of either

LC_MESSAGES or LC_ALL variables, unicode line drawing characters will be used

to draw lines in the Object Browser. This is the case of most Linux

distributions.

In the Libraries view, you can either double click or press <Enter> on a

library name to see its objects. In the Object Browser, the libraries have the

color defined by the PreProc highlighting group. 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 type of R object:

PreProc libraries

Number numeric

String character

Special factor

Boolean logical

Type list

Function function

Statement s4

One limitation of the Object Browser is that objects made available by the

command `data()` are only links to the actual objects (promises of lazily

loading the object when needed) and their real classes are not recognized in

the GlobalEnv view. The same problem happens when the `knitr` option

`cache.lazy=TRUE`. If you press <Enter> over the name of the object in the

Object Browser, it will be actually loaded by the command (ran in the

background):

You can toggle the state of a line as either commented or uncommented by

typing <LocalLeader>xx. The string used to comment the line will be "# ",

"## " or "### ", depending on the values of |vimrplugin_indent_commented| and

|r_indent_ess_comments|.

You can also add the string "# " to the beginning of a line by typing

<LocalLeader>xc and remove it with <LocalLeader>xu. In this case, you can set

the value of vimrplugin_rcomment_string to control what string will be added

to the beginning of the line. Example:

Finally, you can also add comments to the right of a line with the

<LocalLeader>; shortcut. By default, the comment starts at the 40th column,

which can be changed by setting the value of r_indent_comment_column, as

below:

If the line is longer than 38 characters, the comment will start two columns

after the last character in the line. If you are running <LocalLeader>; over a

selection of lines, the comments will be aligned according to the longest

line.

Note: While typing comments the leader comment string is automatically added

to new lines when you reach 'textwidth' but not when you press <Enter>.

Please, read the Vim help about 'formatoptions' and |fo-table|. For example,

you can add the following line to your |vimrc| if you want the comment string

being added after <Enter>:

Tip: You can use Vim substitution command `:%s/#.*//` to delete all comments

in a buffer (see |:s| and |pattern-overview|).

*:RBuildTags*

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 calls the R

function `rtags()` to build the tags file for the R scripts in the current

directory. Please read |r-plugin-tagsfile| to learn how to create a tags file

referencing source code located in other directories, including the entire R

source code.

*r-plugin-tmux*

When running either GVim or Vim in a terminal emulator (Linux/Unix only), the

Vim-R-plugin will use Tmux to start R in a separate terminal emulator. R will

be running inside a Tmux session, but you will hardly notice any difference

from R running directly in the terminal emulator. The remaining of this

section refers to the case of starting R when Vim already is in a Tmux

session, that is, if you do:

In this case, the terminal window is split in two regions: one for Vim and the

other for Tmux. Then, it's useful (but not required) to know some Tmux

commands. After you finished editing the file, you have to type `exit` to quit

the Tmux session.

Note: Starting GVim within a Tmux session is not supported.

*r-plugin-tmux-setup*

If, as recommended, you always prefer to run Tmux before running you have to

create your `~/.tmux.conf` if it does not exist yet. You may put the lines

below in your `~/.tmux.conf` as a starting point to your own configuration

file:

The Tmux configuration file suggested above configures Tmux to use vi key

bindings. It also configures Tmux to react to mouse clicks. You should be able

to switch the active pane by clicking on an inactive pane, to resize the panes

by clicking on the border line and dragging it, and to scroll the R Console

with the mouse wheel. When you use the mouse wheel, Tmux enters in its

copy/scroll back mode (see below).

The configuration script also sets <C-a> as the Tmux escape character (the

default is <C-b>), that is, you have to type <C-a> before typing a Tmux

command. Below are the most useful key bindings for Tmux with the tmux.conf

shown above:

<C-a>arrow keys : Move the cursor to the Tmux panel above, below, at the

right or at the left of the current one.

<C-a><C-Up> : Move the panel division upward one line, that is, resize

the panels. Repeat <C-Up> to move more. <C-Down> will

move the division downward one line. If you are using

the vertical split, you should use <C-Left> and

<C-Right> to resize the panels.

<C-a>[ : Enter the copy/scroll back mode. You can use <PgUp>,

<PgDown> and vi key bindings to move the cursor around

the panel. Press q to quit copy mode.

<C-a>] : Paste the content of Tmux paste buffer.

<C-a>z : Hide/show all panes except the current one.

Note: If you mistakenly press <C-a><C-z>, you have to

type `fg` to get Tmux back to the foreground.

While in the copy and scroll back mode, the following key bindings are very

useful:

q : Quit the copy and scroll mode.

<Space> : Start text selection.

v<Space> : Start rectangular text selection.

<Enter> : Copy the selection to Tmux paste buffer.

Please, read the manual page of Tmux if you want to change the Tmux

configuration and learn more commands. To read the Tmux manual, type in the

terminal emulator:

Note: Because <C-a> was configured as the Tmux escape character, it will not

be passed to applications running under Tmux. To send <C-a> to either R or Vim

you have to type <C-a><C-a>.

You do not need to copy code from Vim to R because you can use the plugin's

shortcuts to send the code. For pasting the output of R commands into Vim's

buffer, you can use the command |:Rinsert|. If you want to copy text from an

application running inside the Tmux to another application also running in

Tmux, as explained in the previous subsection, you can enter in Tmux

copy/scroll mode, select the text, copy it, switch to the other application

pane and, then, paste.

However, if you want to copy something from either Vim or R to another

application not running inside Tmux, Tmux may prevent the X server from

capturing the text selected by the mouse. This can be prevented by

pressing the <Shift> key, as it suspends the capturing of mouse events

by tmux. If you keep <Shift> pressed while selecting text with the mouse,

it will be available in the X server clipboard and can be inserted

into other windows using the middle mouse button. It can of course also be

inserted into a tmux window using <Shift> and the middle mouse button.

*r-plugin-remote*

The Vim-R-plugin can not send commands from a local Vim to a remote R, but you

can access the remote machine through ssh and run Tmux, Vim and R in the

remote machine. Tmux should not be running in the local machine because some

environment variables could pass from the local to the remote Tmux and confuse

the plugin.

If you need to access Vim in a remote Unix machine through ssh, and if you

want to get omnicompletion, syntax highlight of function names and the Object

Browser working properly, instead of Vim, it is recommended that you use

Neovim because it does not require the X Server to be fully functional. If

you cannot use Neovim, then you have to:

- Enable X11 Forwarding in the remote machine.

- Have Vim in the remote machine compiled with |clientserver| feature.

- Have the X Server running in the local machine.

- Pass either the `-X` or the `-Y` argument to ssh, as in the examples

below:

- Start Tmux and, then, Vim with the |--servername| argument:

With Tmux, you can detach the Vim-R session and reattach it later (but the

connection with the XServer could be lost in the process). This is useful if

you plan to begin the use the Vim-R-plugin in a machine and later move to

another computer and access your previous Vim-R session remotely. Below is the

step-by-step procedure to run the Vim-R remotely:

- Start Tmux:

tmux

- Start Vim:

vim script.R

- Use Vim to start an R session:

<LocalLeader>rf

- Send code from Vim to R, and, then, detach Vim and R with <C-a>d

The command will be <C-b>d if you have not set <C-a> as the escape

character in your ~/.tmux.conf.

- Some time later (even if accessing the machine remotely) reattach the

Tmux session:

tmux attach

*r-plugin-known-bugs*

Known bugs that will not be fixed are listed in this section. Some of them can

not be fixed because they depend on missing features in either R or Vim;

others would be very time consuming to fix without breaking anything.

The R's `source()` function of the base package prints an extra new line

between commands if the option echo = TRUE, and error and warning messages are

printed only after the entire code is sourced. This makes it more difficult to

find errors in the code sent to R. Details:

https://stat.ethz.ch/pipermail/r-devel/2012-December/065352.html

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.