*R.nvim.txt* Plugin to work with R

Authors: R.nvim team (see: https://github.com/R-nvim)

Version: 0.9.0

For Neovim >= 0.10.4

1. Overview |R.nvim-overview|

2. Main features |R.nvim-features|

3. Installation |R.nvim-installation|

4. Use |R.nvim-use|

5. Known bugs and workarounds |R.nvim-known-bugs|

6. Options |R.nvim-options|

7. Custom key bindings |R.nvim-key-bindings|

8. History |R.nvim-history|

1. Overview *R.nvim-overview*

This plugin improves the support for editing R code with Neovim.

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.

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/jalvesaq/Nvim-R/discussions

Git pull requests are welcome.

2. Main features *R.nvim-features*

* 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 LaTeX commands.

* Auto completion (with `cmp-r`):

- R objects (.GlobalEnv and loaded packages).

- function arguments.

- knitr chunk options.

- Quarto cell options.

* Ability to see R's documentation in an editor buffer:

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

- See R documentation formatted as Rmd.

* Object Browser (.GlobalEnv and loaded packages):

- Tree view of objects.

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

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

* Limited support for debugging R functions.

* Get the `params` variable from Quarto and Rmd YAML header and Create and

update the corresponding `params` list in `.GlobalEnv`.

* Most of the plugin's behavior is customizable.

3. Installation *R.nvim-installation*

The installation process is described in four sections:

3.1. Installation of dependencies

3.2. Installation of the plugin

3.3. Troubleshooting

3.4. Optional steps

3.1. Installation of dependencies

Before installing the plugin, you should install its dependencies:

Main dependencies:

Neovim >= 0.10.4:

https://github.com/neovim/neovim/releases

See also: https://github.com/neovim/neovim/wiki/Installing-Neovim

nvim-treesitter:

https://github.com/nvim-treesitter/nvim-treesitter

You have to enable highlighting by tree-sitter and install parsers for

`r`, `markdown`, `markdown_inline`, `rnoweb`, `yaml`, `latex`, and `csv`.

cmp-r (for auto-completion):

https://github.com/R-nvim/cmp-r

R >= 4.0.0:

http://www.r-project.org/

Make and C compiler

GNU `make` and a C compiler (e.g. `gcc` or `clang`) must be installed to

build the the R package `nvimcom` which is included in R.nvim and is

automatically installed and updated whenever necessary.

On Windows, you have to install Rtools to be able to build `nvimcom`:

https://cran.r-project.org/bin/windows/Rtools/

Note about the R package `nvimcom`:

You do not need to load nvimcom in your .Rprofile because the R.nvim

plugin sets the environment variable `R_DEFAULT_PACKAGES`, including

`nvimcom` in the list of packages to be loaded on R startup. However,

if you set the option `defaultPackages` in a .Rprofile, you should

include "nvimcom" among the packages to be loaded (see

|nvimcom-not-loaded|).

Quarto: required to complete chunk options in `#|` comments in Quarto, Rmd

and Rnoweb documents: https://quarto.org/

Additional dependencies for editing Rnoweb documents:

latexmk: Automate the compilation of LaTeX documents.

See examples in |latexcmd|.

PDF viewer with SyncTeX support and capable of automatically reloading

documents. This is required only if you edit Rnoweb files.

On Linux and other Unix systems: Zathura.

On macOS: Skim.

On Windows: SumatraPDF.

Suggestions for Unix (Linux, macOS, etc.):

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

Tmux is required only if you want to run R in an external

terminal emulator or in a Tmux split panel

(see |external_term|).

colorout >= 1.3-1:

https://github.com/jalvesaq/colorout/releases

Colorizes the R output in terminal emulators.

(Mostly useful if running R in an external terminal emulator.

See |external_term|). You should put in your Rprofile:

`library(colorout)`

Suggestions for bibliographic completion from Zotero in RMarkdown (`.Rmd`) and

Quarto (`.qmd`) documents:

- https://github.com/jalvesaq/zotcite

- https://github.com/jalvesaq/cmp-zotcite

3.2. Installation of the plugin

It is recommended that you use a plugin manager to install R.nvim. See the

Wiki:

https://github.com/R-nvim/R.nvim/wiki

3.3. Troubleshooting (if the plugin doesn't work)

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 .qmd file. The key bindings will not be active while

editing either unnamed files or files with name extensions other than the

mentioned above: However, see:

https://github.com/jalvesaq/Nvim-R/wiki/Enable-Nvim-R-for-any-file-type

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.

Run `:checkhealth r` to check if some dependencies are installed and if

treesitter is working properly.

Run `:RDebugInfo` to see information useful to fix some common issues.

To see on the R Console messages received by `nvimcom`, put in your

`~/.Rprofile`:

>r

options(nvimcom.verbose = 5)

<

If R does not start with the <LocalLeader>rf command and you get an error

message instead, you may want to set the path to the R executable (see

|R_path|).

*nvimcom-not-loaded*

If you see the following message in the R console:

Try quitting both R and Neovim and starting them again.

If you still see the message "The package nvimcom wasn't loaded yet" after

starting R, then R.nvim could not induce R to load nvimcom. R.nvim sets the

environment variable `R_DEFAULT_PACKAGES` before starting R. If the variable

already exists, the string ",nvimcom" is appended to it. However, if you set

the option `defaultPackages` in your .Rprofile or in a .Rprofile in the

current directory, the environment variable will be overridden. Thus, if you

have to set the option `defaultPackages`, you should include "nvimcom" among

the packages to be loaded. You might want to include "nvimcom" only if R was

started by R.nvim, as in the example below:

>r

if(Sys.getenv("RNVIM_TMPDIR") == ""){

options(defaultPackages = c("utils", "grDevices", "graphics",

"stats", "methods"))

} else {

options(defaultPackages = c("utils", "grDevices", "graphics",

"stats", "methods", "nvimcom"))

}

<

Finally, run the command `:RDebugInfo` after <LocalLeader>rf and check the

path where nvimcom was installed.

On Windows, nvimcom compilation will fail if your `.Rprofile` outputs anything

during R Startup. It will also fail with a message about `--slave` not being a

`gcc` option if either `make.exe` or `gcc.exe` from RTools are not the first

ones found in your systems' `PATH` (see |R_path| and |Rtools-path|).

3.4. Optional steps

The plugin should work without the need of any configuration right after

installed, but if you do not like how the plugin works, you could look at the

section |R.nvim-options| to see if there is an option that could make you

happier.

You can also install additional plugins to get other useful functionalities to

edit R code. Please, access R.nvim's wiki:

https://github.com/R-nvim/R.nvim/wiki

4. Use *R.nvim-use*

By default, R.nvim will run R in a built-in terminal emulator, but you can

change this behavior (see |external_term|).

4.1. Key bindings

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

To use the plugin, open a .R, .Rnw, .Rd, .Rmd or .qmd file with Neovim

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

bindings to send commands to R.

The default key binding to quit R is <LocalLeader>rq, but if you quit Neovim

with R still running in a Neovim's built-in terminal emulator, R.nvim will

send to R the command `quit(save = "no")` (see the |auto_quit| option).

This plugin has many key bindings. Not all key bindings are enabled in all

file types supported by the plugin (r, rnoweb, rhelp, rmd, and quarto).

To see the list of mappings, do in Normal mode:

>vim

:RMapsDesc

<

Please see |R.nvim-key-bindings| to learn how to customize the key bindings.

R syntax uses " <- " to assign values to variables which is inconvenient to

type. In insert mode, typing <M--> will write " <- ". Note: You can't map

<C-=> to `<Plug>RInsertAssign` because in Neovim only alphabetic letters can

be mapped in combination with the CTRL key.

In Rnoweb files, if the cursor is in an empty line in Insert mode, pressing

`<M-r>` will insert `<<>>=\n@`. If the line is not empty, it will insert

`\Sexpr{}`. You can map the "less than" symbol to `<Plug>RnwInsertChunk` to

emulate Nvim-R behavior.

In Rmd and Quarto files, typing <M-r> in Insert mode will insert chunk

delimiters. In addition to creating an empty chunk block, the key strokes will

be converted to inline R delimiters if the cursor is not at the beginning of

the line. You can map a single backtick to `<Plug>RmdInsertChunk` to emulate

the default behavior of Nvim-R.

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.

If it has more than one line (a selection of lines, a block of lines between

two marks, a paragraph etc) and if the number of lines is higher than

|max_paste_lines|, 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. See the option `source_args` If you

want to see what lines are being sourced when sending a selection of lines.

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

If the cursor is between manually inserted marks (a-z), the plugin will send

the lines between them to R if you press <LocalLeader>bb. If the cursor is

above the first mark, the plugin will send from the beginning of the file to

the mark. If the cursor is below the last mark, the plugin will send from the

mark to the end of the file. The mark above the cursor is included and the

mark below is excluded from the block to be sent to R. To create a mark, press

m<letter> in Normal mode (see |mark|). For example, consider the following

code (with line numbers):

In Normal mode, go to line 2 and press `ma`; go to line 6 and press `mb`; go

to line 4 and press `<LocalLeader>bb` to send lines 2 to 5 to R. Normally, Vim

marks are not visible, but there are plugins that highlight them.

Sending a selection of lines is actually a special case of sending a marked

block with the marks being `'<` and `'>`. That is the reason why the command

to send selection also works in Normal mode: it will send the lines that

were selected for the last time.

You can also use the command `:RSend` to type and, then, send a line of code

to R.

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, Quarto 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, Neovim will

save the current buffer if it has any pending changes before performing the

tasks. After <LocalLeader>ao, Neovim 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 |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.

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

under the cursor formatted as a `rmd` file. 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:

>r

y <- rnorm(100)

x <- rnorm(100)

m <- lm(y ~ x)

summary(x)

summary(m)

<

To get help on an R topic, you can also type in Neovim (Normal mode):

>vim

:RHelp topic

<

You may close the R documentation window by simply pressing `q`. R

documentation is open in a 'modifiable' buffer to allow you to edit the

code in the "Examples" section. Press `<LocalLeader>`gn to jump to the

next section of R code ("Usage" or "Examples" section) and use R.nvim

key bindings to send code to the R Console.

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, and you can configure R.nvim to call an external application to

display the data.frame or matrix (see |view_df|). All files involved in these

operations are created in R.nvim's temporary directory and deleted when R

quits.

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

In Normal mode `:RStop` sends to R SIGINT which is the same signal sent when

you press CTRL-C into R's Console. If R does not quit normally, you can kill

it with the `:RKill` command.

*:RInsert*

*:RFormat*

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 of R from its console to Neovim. For example, to insert

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

in Neovim:

>vim

:RInsert dput(levels(var))

<

The command `:RFormat` calls the function `style_text()` (if the package

`styler` is installed) to format the selected lines. If no text is selected,

either `style_file()` is called to format the entire buffer. The command only

works if R is running. The value of 'shiftwidth' is passed as `indent_by`.

4.2. Editing Rnoweb files

See |rnoweb-chunks| to know how to properly include chunk options.

In Rnoweb files (.Rnw), when the cursor is over the `@` character, which

finishes an R chunk, the command to send a line to R Console will make 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

You can also press <LocalLeader>gt to go the corresponding line in the

generated .tex file (if SyncTeX is enabled).

The commands <LocalLeader>cc and cd 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 Rnoweb 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 (SyncTeX 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>

Skim: <S-Cmd-Click>

Sumatra: <Double-click>

In any case, the PDF viewer must be started by the R.nvim plugin. See

|R.nvim-SyncTeX| for details.

4.3. Auto-completion

If `cmp-r` (a source for `nvim-cmp`) is installed, Neovim can

automatically complete the names of R objects as you type them.

R.nvim does not complete the names of all functions of all installed packages

(see |start_libs|); only of loaded libraries.

For both `library()` and `require()`, when completing the first argument, the

popup list shows the names of installed packages.

4.4. The Object Browser

You have to use <LocalLeader>ro to either open or close the Object Browser on

the same tab page. If it is already open on another tab page, it will be

closed there and opened again in the current one. The Object Browser has two

views: .GlobalEnv and Libraries. If you press <Enter> 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:

>r

library("haven")

d <- read_spss("/path/to/spss/dataset.sav")

<

In the Object Browser window, while in Normal mode, you can either press

<Enter> or double click over a data.frame or list to show/hide its elements.

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

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 <Enter> over the name of the object

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

background):

>r

obj <- obj

<

Notes:

- If either the Object Browser is open or cmp-r is installed, the

list of .GlobalEnv objects will be automatically updated by R after each

successful command evaluation. This may slowdown R if its workspace has

too many objects, data.frames with too many columns or lists with too many

elements.

- Names of objects are stupidly truncated if they occupy more than 62 bytes.

This means that Unicode sequences might be split and become invalid.

- Active bindings are not included in the list of objects for auto

completion. Also, they are not included in the Object Browser.

4.5. Build a tags file to jump to function definitions *RBuildTags*

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

4.6. Syntax highlight of .Rout files

You can set both foreground and background colors of R output in your

`init.lua`. The example below is for an interface of Neovim with

'termguicolors' (see |true-color|):

>lua

if vim.o.termguicolors then

vim.g.rout_color_input = "guifg=#9e9e9e"

vim.g.rout_color_normal = "guifg=#ff5f00"

vim.g.rout_color_number = "guifg=#ffaf00"

vim.g.rout_color_integer = "guifg=#feaf00"

vim.g.rout_color_float = "guifg=#fdaf00"

vim.g.rout_color_complex = "guifg=#fcaf00"

vim.g.rout_color_negnum = "guifg=#d7afff"

vim.g.rout_color_negfloat = "guifg=#d6afff"

vim.g.rout_color_date = "guifg=#00d7af"

vim.g.rout_color_true = "guifg=#5dd685"

vim.g.rout_color_false = "guifg=#ff5d5e"

vim.g.rout_color_inf = "guifg=#10aed7"

vim.g.rout_color_constant = "guifg=#5fafcf"

vim.g.rout_color_string = "guifg=#5fd7af"

vim.g.rout_color_error = "guifg=#ffffff guibg=#c40000"

vim.g.rout_color_warn = "guifg=#d00000"

vim.g.rout_color_index = "guifg=#d0d080"

end

<

If you prefer that R output is highlighted using your current `colorscheme`,

put in your `init.lua`:

>lua

vim.g.rout_follow_colorscheme = true

<

4.7. Debugging R functions (Unix only) *debug-R-functions*

`R.nvim` has limited debugging facilities available on Unix systems (not

available on Windows). To debug a function with R.nvim you have to do the

following:

1. Load the functions into R either by a) sourcing the R script where the

function is with the `source()` function of the `base` package or b)

loading all desired functions with `devtools::load_all(<relevant path>)`.

2. Flag a function or line of code within a function to use the debugger.

This can be done by using the `debug` functions or setting a breakpoint

with the `browser` functions from the `base` package. To use `debug`,

in the R Console, run either `debug(funcname)` or `debugonce(funcname)`

where `funcname` is the name of the function (not quoted). R.nvim will

send this command to R Console if you press <LocalLeader>bg in Normal

mode with the cursor over the function name. Use `<LocalLeader>ud` with the cursor on a function to undebug it. An example of using

`browser` is shown later in the documentation.

3. Call the function.

See `:RHelp browser` for available commands in debugging mode.

For example, if you have a file named `my_function.R` with the following

contents:

>r

add.one <- function(x){

y <- x + 1

print(y)

return(invisible(NULL))

}

<

You could debug the `add.one()` function from another script such as:

>r

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:

>r

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:

>r

add.one <- function(x){

y <- x + 1

if(x > 9)

browser()

print(y)

return(invisible(NULL))

}

<

One limitation is that R.nvim also does not help you setting breakpoints.

You have to set them manually as explained above.

Another limitation of R.nvim 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, R.nvim 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 debugged is the

QuickFixLine (see |hl-QuickFixLine|). Its foreground and background colors are

defined by your colorscheme.

5. Known bugs and workarounds *R.nvim-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 Neovim;

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

5.1. R must be started by R.nvim

The communication between Neovim and R will work only if R was started by the

running Neovim instance through the <LocalLeader>rf command. If you use R.nvim

to start R in an external terminal and, then close Neovim and open it again,

there will be no communication between R and the new Neovim instance.

Please see the explanation on the communication between Neovim and R at the

end of

https://github.com/R-nvim/R.nvim/blob/master/README.md

5.2. Cannot raise window (web browser or PDF viewer)

When you generate an HTML or PDF document from a Quarto, Rmd, or Rnoweb

document, R.nvim can raise (focus) the web browser or PDF viewer if you are

using Xorg or Sway (both on Linux). The necessary code was not written yet for

other systems (macOS, Windows, and most Wayland compositors on Linux). Please,

see the function `utils.get_focused_win_info()` if you want to fix the issue

on your system.

5.3. Object Browser and auto-completion limitations

New lines in list names (which includes column names in data frames and

matrices) are replaced with blank spaces in the data used by `cmp-r` and the

Object Browser.

Objects from environments accessed with the `browser()` function are not

listed in the Object Browser or during auto-completion with `cmp-r`.

5.4 R code block not recognized within HTML tags

An R code block in a Markdown document is not recognized when within an HTML

tag unless there is an extra empty line between the tag and the beginning of

the block. So, for example, instead of:

We need:

This happens because tree-sitter-markdown follows the CommonMark

specification, which treats anything that follows an HTML tag as verbatim

until an empty line is found.

5.5 Old style chunks not properly recognized in Rnoweb *rnoweb-chunks*

Chunks of R code with old style headers are not correctly recognized by

tree-sitter and, consequently, it's not properly highlighted and sent to the

R Console. So, instead of:

You should write:

5.6 You can't put `syntax enable` in your `init.vim` (macOS only)

It seems that if you put the command `syntax enable` in your `init.vim` on

macOS, file type plugins are immediately sourced. Consequently, all R.nvim

variables will be used at their default values. The workaround is do not

include the superfluous command `syntax enable` in the `init.vim`. For

details, please, access:

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

5.7. Windows bugs and limitations

Wrong message that "R is busy"

On Windows, when code is sent from Neovim to R Console, the nvimcom library

sets the value of the internal variable `r_is_busy` to 1. The value is set

back to 0 when any code is successfully evaluated. If you send invalid code to

R, there will be no successful evaluation of code and, thus, the value of

`r_is_busy` will remain set to 1. Then, if you try to update the object

browser, see the R documentation for any function, or do other tasks that

require hidden evaluation of code by R, the nvimcom library will refuse to

do the tasks to avoid any risk of corrupting R's memory. It will tell Neovim

that "R is busy" and Neovim will display this message. Everything should work

as expected again after any valid code is executed in the R Console.

Error if there is no package installed

On Windows, Neovim may fail to recognize that a directory is not writable, and

this is required by R.nvim to detect if it is necessary to create the

directory defined by `$R_LIBS_USER` environment variable. Consequently, R.nvim

does no try to create the directory and nvimcom installation fails. This

problem will happen if you have just installed or upgraded R. The workaround

is to manually open R and install any package with the `install.packages()`

command before using R.nvim.

~/.Rprofile should not output anything

The compilation of `nvimcom` during R startup will fail on Windows if your

`~/.Rprofile` outputs anything. Example of how to replicate the bug:

>r

print("This message will break compilation by gcc!")

<

Send commands to Radian doesn't work well

If you use `radian` as |R_app|, multiple lines will not be correctly

interpreted because `bracketed_paste` is not recognized by terminals on

Windows.

6. Options *R.nvim-options*

The complete list of options and their defined values can be seen with the

command:

>vim

:RConfigShow

<

You may close the window opened by `:RConfigShow` by simply pressing `q`.

|auto_start| Start R automatically

|objbr_auto_start| Start the Object Browser automatically

|built-in-terminal| Options to control Neovim's built-in terminal

|external_term| Command to run R in an external terminal emulator

|silent_term| Do not show terminal errors

|set_home_env| Set the value of $HOME for R (Windows only)

|save_win_pos| Save position of Rgui window (Windows only)

|arrange_windows| Restore position of R window (Windows only)

|pipe_version| Either "native"/"|>" or "magrittr"/"%>%"

|rproj_prioritise| Use .Rproj file to override options

|objbr_place| Placement of Object Browser

|objbr_w| Initial width of Object Browser window

|objbr_h| Initial height of Object Browser window

|objbr_opendf| Display data.frames open in the Object Browser

|objbr_openlist| Display lists open in the Object Browser

|objbr_allnames| Display hidden objects in the Object Browser

|objbr_mappings| Add custom keymap to the Object Browser

|objbr_placeholder| Define the string to substitute for with objects

|compl_data| Limits to completion data (avoid R slowdown)

|nvimpager| Use Neovim to see R documentation

|open_example| Use Neovim to display R examples

|R_path| Directory where R is

|R_app|, |R_cmd| Names of R applications

|R_args| Arguments to pass to R

|start_libs| Objects for auto completion

|Rout_more_colors| More syntax highlighting in R output

|routnotab| Show output of R CMD BATCH in new window

|config_tmux| Don't use a specially built Tmux config file

|rconsole_height| Number of lines of R Console

|rconsole_width| Number of columns of R Console

|register_treesitter| Register treesitter parsers for quarto and rmd files

|min_editor_width| Minimum number of columns of editor after R start

|RStudio_cmd| Run RStudio instead of R.

|listmethods| Do `nvim.list.args()` instead of `args()`

|specialplot| Do `nvim.plot()` instead of `plot()`

|paragraph_begin| Send paragraph from its beginning

|parenblock| Send lines until closing parenthesis

|bracketed_paste| Bracket R code in special escape sequences

|clear_console| Send <C-L> to clear R's console

|source_args| Arguments to R `source()` function

|max_paste_lines| Maximum number of lines to be pasted into R Console

|latexcmd| Command to run on .tex files

|texerr| Show a summary of LaTeX errors after compilation

|sweaveargs| Arguments do `Sweave()`

|rmd_environment| Environment in which to save evaluated rmd code

|rmarkdown_args| Further options to be passed to `rmarkdown::render()`

|quarto_render_args| Options to be passed to `quarto::quarto_render()`

|quarto_preview_args| Options to be passed to `quarto::quarto_preview()`

|clear_line| Clear R Console line before sending a command

|editing_mode| The mode defined in your `~/.inputrc`

|pdfviewer| PDF application used to open PDF documents

|open_pdf| Open PDF after processing Rmd, Quarto or Rnoweb file

|open_html| Open HTML after processing Rmd or Quarto

|insert_mode_cmds| Allow R commands in insert mode

|rmhidden| Remove hidden objects from R workspace

|set_params| Control setting `params` in `.GlobalEnv`

|wait| Time to wait for nvimcom loading

|wait_reply| Time to wait for R reply

|setwd| Directory where to start R

|hook| Lua functions to call after certain events

|user_maps_only| Only user specified key bindings

|disable_cmds| List of commands to be disabled

|tmpdir| Where temporary files are created

|compldir| Where lists for auto completion are stored

|remote_compldir| Mount point of remote cache directory

|view_df| Options for visualizing a data.frame or matrix

|R.nvim-SyncTeX| Options for SyncTeX

|debug| Support for debugging functions

6.1. Automatic start: R and Object Browser *auto_start*

*objbr_auto_start*

By default, you have to start R manually with the command <LocalLeader>rf.

If you want that R starts automatically when you load an R script while

starting Neovim, put in your config:

>lua

auto_start = "on startup"

<

If you want that R starts automatically when you start editing an R script

even if Neovim is already started, put in your config:

>lua

auto_start = "always"

<

The default value of `auto_start` is "no".

See also: |hook|.

If you want to always start the Object Browser immediately after starting R,

put in your config:

>lua

objbr_auto_start = true

<

See also: |hook|.

6.2. R in Neovim built-in terminal *R-built-in-terminal*

*esc_term*

By default, R runs in a Neovim buffer created with the command |:term|,

and the <Esc> key is mapped to stop the Terminal mode and go to Normal mode.

In Terminal mode, What you type is passed directly to R while in Normal mode

Vim's navigation commands work as usual (see |motion.txt|).

If you need the <Esc> key in R, for example if you want to use `vi`, `vim` or

`nvim` within R Console, put in your config:

>lua

esc_term = false

<

Then, you will have to press the default <C-\><C-n> to go from Terminal to

Normal mode.

R.nvim sets the option "editor" to a function that makes the object to be

edited in a new tab when `esc_term` = `true` (the default value).

*close_term*

Neovim does not close its built-in terminal emulator when the application

running in it quits, but R.nvim does close it for you. If you rather prefer

that the terminal remains open after R quitting, put in your config:

>lua

close_term = false

<

Neovim stops automatically scrolling the R Console if you move the cursor to

any line that is not the last one. This emulates the behavior of other

terminal emulator, but considering that (1) R only outputs something after we

send a command to it, and (2) when we send a command to R, we want to see its

output, R.nvim will move the cursor to the last line of R Console before

sending a command to it, forcing the auto scrolling of the terminal. You can

disable this feature with the option:

>lua

auto_scroll = false

<

*hl_term*

You may either use the package colorout (Unix only) to colorize R output or

let Neovim highlight the terminal contents as it was a .Rout file type. Two

advantages of colorout are the possibility of highlighting numbers close to

zero in a different color and the distinction between stdout and stderr. The

value of `hl_term` (`false` or `true`) determines whether Neovim should syntax

highlight the R output, and its default value will be set to `false` if the

package colorout is loaded. If you prefer do not rely on the auto detection

of colorout, you should set the value of `hl_term` in your config. Example:

>lua

hl_term = false

< *OutDec*

Right after starting R, R.nvim will try to detect if either the value of R's

`OutDec` option is `","` or the current R script sets the `OutDec` option. If

you are using Neovim to syntax highlight R's output and it is not correctly

detecting R's `OutDec` option, then, to get numbers correctly recognized, you

should put in your config:

>lua

OutDec = ","

< *setwidth*

On Unix systems, BEFORE sending a command to R Console, if the terminal width

has changed, Neovim will send to nvimcom the command `options(width=X)`,

where X is the new terminal width. You can set the value of `setwidth` to 0 to

avoid the width being set. Example:

>lua

setwidth = 0

<

On Windows, the command is sent to R Console because it would crash R if sent

through nvimcom.

If you have the option 'number' set in your config, R.nvim will calculate the

number of columns available for R as the window width - 6. If you want a

different adjustment, you should set `setwidth` as a negative value between

-1 and -16. Example:

>lua

setwidth = -7

<

You can also set the value of `setwidth` to `2`. In this case, nvimcom will

check the value of the environment variable `COLUMNS` AFTER each command is

executed and if the environment variable exists, R's width option will be set

accordingly. This is the most precise way of setting the option "width", but

it has the disadvantage of setting it only after the command is executed. That

is, the width will be outdated for the first command executed after a change

in the number of columns of the R Console window.

*buffer_opts*

R.nvim sets the options 'winfixwidth' and 'winfixheight' in the window where R

runs. This prevents the window of being automatically resized in some

circumstances. It also sets the option 'nobuflisted'. You can set the value of

`buffer_opts` to define what options should be set in the R Console buffer.

It is a list of Vim options separated by spaces. Example with its default

value:

>lua

buffer_opts = "winfixwidth winfixheight nobuflisted"

<

If you do not want to run R in Neovim's built-in terminal emulator, you

have to install Tmux >= 3.0, and then put in your config:

>lua

external_term = "default"

<