R.nvim adds R support to Neovim, including:
-
Communication with R via Neovim's built-in terminal or tmux
-
A built-in object explorer and autocompletions built from your R environment
-
Keyboard shortcuts for common inserts like
<-
and|>
-
Quarto/R Markdown support
-
...And much more!
Please, see the list of dependencies at section 3.1 of doc/R.nvim.txt.
Here's a (very) minimal configuration using
lazy.nvim (not including R.nvim
dependencies):
{
"R-nvim/R.nvim",
-- Only required if you also set defaults.lazy = true
lazy = false
-- R.nvim is still young and we may make some breaking changes from time
-- to time. For now we recommend pinning to the latest minor version
-- like so:
version = "~0.1.0"
},
A longer example adding some custom behaviour:
{
"R-nvim/R.nvim",
-- Only required if you also set defaults.lazy = true
lazy = false
-- R.nvim is still young and we may make some breaking changes from time
-- to time. For now we recommend pinning to the latest minor version
-- like so:
version = "~0.1.0"
config = function()
-- Create a table with the options to be passed to setup()
local opts = {
hook = {
on_filetype = function()
vim.api.nvim_buf_set_keymap(0, "n", "<Enter>", "<Plug>RDSendLine", {})
vim.api.nvim_buf_set_keymap(0, "v", "<Enter>", "<Plug>RSendSelection", {})
end
}
R_args = {"--quiet", "--no-save"},
min_editor_width = 72,
rconsole_width = 78,
objbr_mappings = { -- Object browser keymap
c = 'class', -- Call R functions
['<localleader>gg'] = 'head({object}, n = 15)', -- Use {object} notation to write arbitrary R code.
v = function()
-- Run lua functions
require('r.browser').toggle_view()
end
},
disable_cmds = {
"RClearConsole",
"RCustomStart",
"RSPlot",
"RSaveClose",
},
}
-- Check if the environment variable "R_AUTO_START" exists.
-- If using fish shell, you could put in your config.fish:
-- alias r "R_AUTO_START=true nvim"
if vim.env.R_AUTO_START == "true" then
opts.auto_start = "on startup"
opts.objbr_auto_start = true
end
require("r").setup(opts)
end,
},
See the plugin documentation for a complete list of possible options. You can also consult the Wiki.
R autocompletion should be configured via another plugin. We recommend cmp-r, which can be minimally configured like so:
{
"R-nvim/cmp-r",
{
"hrsh7th/nvim-cmp",
config = function()
require("cmp").setup({ sources = {{ name = "cmp_r" }}})
require("cmp_r").setup({})
end,
},
},
Note that languageserver can also be used for autocompletions, but using autocompletions from both sources simultaneously is not advised.
Tree-sitter is required to enable much of the functionality of R.nvim, and can be minimally configured like so:
{
"nvim-treesitter/nvim-treesitter",
run = ":TSUpdate",
config = function ()
require("nvim-treesitter.configs").setup({
ensure_installed = { "markdown", "markdown_inline", "r", "rnoweb", "yaml" },
highlight = { enable = true },
})
end
},
Please see the documentation for instructions on usage. For a
complete list of keymaps, see the output of :RMapsDesc
.
R.nvim is still maturing and its public API (configuration options, commands, and some of the Lua internals) may undergo breaking changes from time to time. This project uses semantic versioning to help with this, and we will always bump the minor version, e.g. from 0.1.x to 0.2.0, when we make a breaking change. Users are thus encouraged to pin their installation of R.nvim to the latest minor release and to check the release notes for any breaking changes when upgrading.
Eventually we plan to release a version 1.0.0, at which point we will make a firm commitment to backwards compatibility.
-
reStructuredText support (no longer seems to be widely used).
-
Debugging support (a formal debug adaptor would be a better solution).
-
Legacy omni-completion (we now recommend nvim-cmp).
-
Highlighting functions from
.GlobalEnv
(difficult to make compatible with tree-sitter + LSP highlighting). -
The
echo
argument for functions that send code to R console has been removed. Users can still set thesource_args
to define the arguments that will be passed tobase::source()
and include the argumentecho=TRUE
.max_lines_to_paste
can now be used to set the number of lines which can be sent directly to the R Console without saving the code in a temporary file.
-
<M-->
(i.e.Alt + -
) is now used to insert<-
. This can be configured usingassignment_keymap
. -
R_source
andafter_R_start
have been replaced with more powerfulhook
options. -
nvimpager
, which controls how R documentation is displayed, now has possible options"split_h"
,"split_v"
,"tab"
,"float"
(not implemented yet), and"no"
. -
open_pdf
replacesopenpdf
andopenhtml
; see the documentation for details. -
setwd
replacesnvim_wd
. The new default value is"no"
. -
config_tmux
replacesnotmuxconf
. The new default value istrue
. -
:RFormat
now requires {styler} to be installed; {formatR} is no longer supported.
-
:RMapsDesc
displays the list of key bindings followed by short descriptions. -
:RConfigShow
displays the list of configuration options and their current values.
-
<LocalLeader>sc
sends a piped chain of commands. -
<LocalLeader>ip
installs missing packages detected by languageserver. -
<LocalLeader>sp
splits a filepath under the cursor into individual components concatenated using either"here::here"
(the default),"here"
,"file.path"
,"fs::path"
, or"path"
, depending on howpath_split_fun
is set. Requires nvim-treesitter to be installed). -
<LocalLeader>,
inserts a pipe operator (|>
). This keybinding is configurable usingpipe_keymap
.
-
auto_quit
can be configured to automatically quit R when you quit Neovim. -
rproj_prioritise
can be configured to control how.Rproj
files change the behaviour of R.nvim. Amongst other things, this may affect whether<LocalLeader>,
inserts|>
or%>%
. -
objbr_mappings
can be configured to run R commands on objects in the current session.
None yet! Please let us know if you publish a video presenting R.nvim features 😃
- colorout: If you have [colorout]
installed and are not loading it in your
~/.Rprofile
, it should be version1.3-1
or higher. This is because R.nvim usescolorout::isColorOut()
which in previouscolorout
versions was unduly enabling the output colorizing.
The diagram below shows how the communication between Neovim and R works.
The black arrows represent all commands that you trigger in the editor and that you can see being pasted into R Console. There are three different ways of sending the commands to R Console:
-
When running R in a Neovim built-in terminal, the function
chansend()
is used to send code to R Console. -
When running R in an external terminal emulator, Tmux is used to send commands to R Console.
-
On the Windows operating system, if using the
Rgui.exe
as "external terminal", Nvim-R can send a message to R (nvimcom) which forwards the command to R Console.
The R package nvimcom includes the application rnvimserver which is never used by R itself but is run as a Neovim's job. That is, the communication between the rnvimserver and Neovim is through the rnvimserver standard input and output (green arrows). The rnvimserver application runs a TCP server. When nvimcom is loaded, it immediately starts a TCP client that connects to rnvimserver (red arrows).
Some commands that you trigger are not pasted into R Console and do not output
anything in the R Console; their results are seen in the editor itself. These are
the commands to do auto completion (of names of objects and function
arguments), start and manipulate the Object Browser (\ro
, \r=
and \r-
),
call R help (\rh
or :Rhelp
), insert the output of an R command
(:Rinsert
), and format selected text (:Rformat
).
When new objects are created or new libraries are loaded, nvimcom sends messages that tell the editor to update the Object Browser, update the syntax highlight to include newly loaded libraries and open the PDF output after knitting an Rnoweb file, and compiling the LaTeX result. Most of the information is transmitted through the TCP connection to the rnvimserver, but temporary files are used in a few cases.
-
cmp-r: autocompletion source for nvim-cmp using R.nvim as backend.
-
languageserver: a language server for R.
-
colorout: a package to colorize R's output.
-
Ark: a LSP server/DAP server/Jupyter kernel for R.
-
southernlights: a colourscheme for vim.