-
Notifications
You must be signed in to change notification settings - Fork 1
Use
By default, Nvim-R will run R in a built-in terminal emulator, but you can
change this behavior (see
R_external_term).
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
Nvim-R-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).
| Action | Default shortcut |
|---|---|
| Start R (default) | \rf |
| Start R (custom) | \rc |
| Close R (no save) | \rq |
| Stop (interrupt) R | :RStop |
| Action | Default shortcut |
|---|---|
| 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 |
| Send motion region | \m{motion} |
| 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 |
| Right part of line (cur) | \r |
| Line (evaluate and insert the output a comment) | \o |
| All lines above the current one | \su |
| Action | Default shortcut |
|---|---|
| List space | \rl |
| Clear console | \rr |
| Remove objects and clear console | \rm |
| Print (cur) | \rp |
| Names (cur) | \rn |
| Structure (cur) | \rt |
| View data.frame (cur) in new tab | \rv |
| View data.frame (cur) in horizontal split | \vs |
| View data.frame (cur) in vertical split | \vv |
| View head(data.frame) (cur) in horizontal split | \vh |
| Run dput(cur) and show output in new tab | \td |
| 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, BibTeX and PDF (cur file) (Linux/Unix) | \kb |
| Knit and PDF (cur file) | \kp |
| Knit and Beamer PDF (cur file) | \kl |
| Knit and HTML (cur file, verbose) | \kh |
| Knit and ODT (cur file) | \ko |
| Knit and Word Document (cur file) | \kw |
| Markdown render (cur file) | \kr |
| Spin (cur file) (only .R) | \ks |
| Open attachment of reference (Rmd, Rnoweb) | \oa |
| Open PDF (cur file) | \op |
| Search forward (SyncTeX) | \gp |
| Go to LaTeX (SyncTeX) | \gt |
| Debug (function) | \bg |
| Undebug (function) | \ud |
| Build tags file (cur dir) | :RBuildTags |
| Action | Default shortcut |
|---|---|
Insert <-
|
_ |
| Complete object name | CTRL-X CTRL-O |
| 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 |
| Action | Default shortcut |
|---|---|
| Open/Close | \ro |
| Expand (all lists) | \r= |
| Collapse (all lists) | \r- |
| Toggle (cur) | Enter |
| Action | Default shortcut |
|---|---|
| Help (plugin) | |
| Help (R) | :Rhelp |
Please see Nvim-R-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 the R Console. 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 R the command to source the file.
To send the line currently under the cursor to the R Console 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 <LocalLeader>m{motion} command sends the
lines from the motion command that follows <LocalLeader>m, e.g.
<LocalLeader>m} (from the current line to the end of paragraph) or
<LocalLeader>m3j (the next 3 lines including the current line).
You can also use the command :RSend to type and, then, send a line of code
to R. If you use this command frequently, you may consider creating a map for
it in your vimrc. For example:
nmap <LocalLeader>: :RSendObserve that there is an empty space after :RSend, so you do not have to
type it.
The command <LocalLeader>o runs in the background the R command print(line),
where line is the line under the 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 commands that send, sweave or knit the current buffer, 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 R_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
R_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 first 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:
y <- rnorm(100)
x <- rnorm(100)
m <- lm(y ~ x)
summary(x)
summary(m)Nvim-R will not check the class of the first object if the = operator is
present. For example, in the two cases below you would get the generic help
for summary:
summary(object = x)
summary(object = m)To get help on an R topic, you can also type in Vim (Normal mode):
:Rhelp topicThe 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 omni completion (see
R_start_libs). You may close
the R documentation buffer by simply pressing q.
The command <LocalLeader>td will run dput() with the object under cursor as
argument and insert the output in a new tab. The command <LocalLeader>rv will
also run dput() with the object under cursor as argument and show the output
in a new tab, while <LocalLeader>vs will show it in a horizontal split, and
<LocalLeader>vv will show it in a vertical split.
However, if the object under the cursor is a data.frame or a matrix, instead
of displaying the output of dput(), the commands will save the data.frame or
matrix in a text file with values separated by tab characters and display this
file. The command <LocalLeader>vh will show the head() of the data.frame or
matrix in a horizontal split that opens above the current window. This behavior
can be customized with new mappings (see
Nvim-R-df-view-mappings
and Nvim-R-df-view), and you can configure
Nvim-R to call an external application to display the data.frame or matrix. All
files involved in these operations are created in Nvim-R's temporary directory
and deleted when R quits.
When completing object names (CTRL-X CTRL-O) you have to press CTRL-N to go
forward in the list and CTRL-P to go backward (see |popupmenu-completion|).
For rnoweb, rmd and rrst file types, CTRL-X CTRL-O can also be used to
complete knitr chunk options if the cursor is inside the chunk header.
If R is not running the completion will be based on information from the
packages listed by
R_start_libs (provided that
the libraries were loaded at least once during a session of Nvim-R 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 both library() and require(), when completing the first
argument, the popup list shows the names of installed packages, but only if R is
running.
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:
:Rinsert dput(levels(var))The output inserted by :Rinsert is limited to 5012 characters.
Rformat
The command :Rformat calls the function style_text() (if the package
styler is installed) or the function tidy_source() (if the package
formatR is installed) to format either the entire buffer or the selected
lines. The command only works if R is running. If style_text() is used the
value of 'shiftwidth' is passed as indent_by, and if tidy_source() is
used, 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:
Go to the next chunk of R code:
[count]<LocalLeader>gnGo to the previous chunk of R code:
[count]<LocalLeader>gNYou can also press <LocalLeader>gt to go the corresponding line in the
generated .tex file (if SyncTeX is enabled).
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. You can jump
from the Rnoweb file to the PDF (forward search) with the command
<LocalLeader>gp. The command to jump from a specific location in the PDF to
the corresponding line in the Rnoweb (backward search) is specific to each pdf
viewer:
-
Zathura:
<C-LeftMouse> -
Evince:
<C-LeftMouse> -
Okular:
<S-LeftMouse> -
Skim:
<S-Cmd-Click> -
Sumatra:
<Double-click>
In any case, the pdf viewer must be started by the Nvim-R plugin. See Nvim-R-SyncTeX for 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
R_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 both as you type them
and when CTRL-X CTRL-O is pressed in insert mode (to disable these features,
see R_auto_omni and
R_set_omnifunc; see also |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 also shows the function arguments in a attached float
window.
If a data.frame is found, while building the list of objects, the columns in
the data.frame are added to the list but they are shown in the menu only after
you have inserted the '$' symbol after the data.frame name.
Only the names of objects in .GlobalEnv and in loaded libraries are completed.
If R is not running, only objects of libraries listed in
R_start_libs will have their
names completed. The omni completion menu will be truncated if the buffer being
transmitted becomes too big (see |R_omni_size|).
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 $NVIMR_TMPDIR
directory and is deleted when you quit Vim. The other files are stored in the
$NVIMR_COMPLDIR directory, are automatically updated and remain available
until you manually delete them.
You have to use <LocalLeader>ro to either open or close the Object Browser.
The Object Browser has two views: .GlobalEnv and Libraries. If you press
on the first line of the Object Browser it will toggle the view
between the objects in .GlobalEnv and the currently loaded libraries.
In the .GlobalEnv view, if a data.frame column has the attribute "label", it
will also be displayed. For instance, the code below would make the Object
Browser display the variable labels of an imported SPSS dataset:
library(foreign)
d <- read.spss("/path/to/spss/dataset.sav", to.data.frame = TRUE)
vlabs <- attr(d, "variable.labels")
for(n in names(vlabs))
attr(d[[n]], "label") <- vlabs[[n]]In the Object Browser window, while in Normal mode, you can either press
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 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:
| Highlighting Group | Object type |
|---|---|
| PreProc | libraries |
| Include | environment |
| Number | numeric |
| String | character |
| Special | factor |
| Boolean | logical |
| Type | data.frame |
| StorageClass | list |
| Structure | s4 |
| Function | function |
| Statement | control flow (for, while, break, etc) |
| Comment | promise (lazy load object) |
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. However, if you press over the name of the object
in the Object Browser, it will be actually loaded by the command (ran in the
background):
obj <- objNotes:
-
The Object Browser enables the automatic update of the data for the omni completion of .GlobalEnv objects, and this may slowdown R if its workspace has too many objects, data.frames with too many columns or lists with too many elements (see
R_hi_fun_globenv. -
Names of objects are stupidly truncated if they occupy more than 62 bytes. This means that Unicode sequences might be split and become invalid.
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 R_indent_commented and
r_indent_ess_comments (see R_rcomment_string).
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 R_rcomment_string to control what string will be added to the
beginning of the line. For example:
let R_rcomment_string = '# '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:
let r_indent_comment_column = 20If 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>:
autocmd FileType r setlocal formatoptions-=t formatoptions+=croqlTip: You can use Vim substitution command :%s/#.*// to delete all comments
in a buffer (see |:s| and |pattern-overview|).
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
functions rtags() and etags2ctags to build the tags file for the R scripts
in the current directory. Please read |Nvim-R-tagsfile| to learn how to create
a tags file referencing source code located in other directories, including
the entire R source code.
The Nvim-R-Plugin has limited debugging facilities available on Unix systems (not available on Windows). To debug a function with Nvim-R you have to do the following:
-
Source the R script where the function is with the
source()function of thebasepackage. -
In the R Console, run the command
debug(funcname)wherefuncnameis the name of the function (not quoted). Nvim-R will send this command to R Console if you press<LocalLeader>dbin Normal mode with the cursor over the function name. -
Call the function.
See :Rh browser for available commands in debugging mode.
For example, if you have a file named my_function.R with the following
contents:
add.one <- function(x){
y <- x + 1
print(y)
return(invisible(NULL))
}You could debug the add.one() function from another script such as:
source("path/to/my_function.R")
debug(add.one)
add.one(7)If you do not want to start debugging the function from its first line,
instead of calling debug(funcname) before calling the function, you should
add the line browser() to the function at the line where the debugging
session should start. Example:
add.one <- function(x){
y <- x + 1
browser()
print(y)
return(invisible(NULL))
}If you want a conditional breakpoint, you should call the browser() command
only if a condition is satisfied. Example:
add.one <- function(x){
y <- x + 1
if(x > 9)
browser()
print(y)
return(invisible(NULL))
}One limitation is that Nvim-R also does not help you setting breakpoints. You have to set them manually as explained above.
Another limitation of Nvim-R is that it might be unable to jump to the line in
the source code that is being evaluated if either you have sent the function
directly to the R Console or the function has been sent by the knitr
package, without calling the function source(). In either case, Nvim-R will
try to find the pattern funcname <- function( in the buffer being edited. If
the pattern is found, the cursor will jump to its position.
The highlighting group used to highlight the line being debuged is the
QuickFixLine (see hl-QuickFixLine). Its foreground and background colors are
defined by your colorscheme, but you can change them in your vimrc (see
cterm-colors and gui-colors). Example:
hi QuickFixLine ctermfg=231 ctermbg=23 guifg=white guibg=#005f5f