README.md

R.nvim

This is the development code of R.nvim which improves Neovim's support to edit R scripts.

Installation

If you use a plugin manager, follow its instructions on how to install plugins from GitHub. Users of lazy.nvim who opted for defaults.lazy=true have to configure R.nvim with lazy=false. Examples of configuration for lazy.nvim (see also cmp-r):

Minimal configuration:

  {
    "R-nvim/R.nvim",
    lazy = false
  },
  {
    "nvim-treesitter/nvim-treesitter",
    run = ":TSUpdate",
    config = function ()
      require("nvim-treesitter.configs").setup({
        ensure_installed = { "markdown", "markdown_inline", "r", "rnoweb" },
      })
    end
  },
  "R-nvim/cmp-r",
  {
    "hrsh7th/nvim-cmp",
    config = function()
      require("cmp").setup({ sources = {{ name = "cmp_r" }}})
      require("cmp_r").setup({ })
    end,
  },

More complex configuration (for R.nvim only):

    {
        "R-nvim/R.nvim",
        config = function ()
            -- Create a table with the options to be passed to setup()
            local opts = {
                R_args = {"--quiet", "--no-save"},
                hook = {
                    on_filetype = function ()
                        -- This function will be called at the FileType event
                        -- of files supported by R.nvim. This is an
                        -- opportunity to create mappings local to buffers.
                        vim.api.nvim_buf_set_keymap(0, "n", "<Enter>", "<Plug>RDSendLine", {})
                        vim.api.nvim_buf_set_keymap(0, "v", "<Enter>", "<Plug>RSendSelection", {})
                    end
                },
                min_editor_width = 72,
                rconsole_width = 78,
                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 = 1
                    opts.objbr_auto_start = true
                end
                require("r").setup(opts)
            end,
        lazy = false
    },

The complete list of options is in the documentation. See also the Wiki.

Usage

Please read the plugin's documentation for instructions on usage. See also the output of :RMapsDesc.

Transitioning from Nvim-R

Changes

During the conversion of VimScript to Lua, we decided to end support for features that were useful in the past but no longer sufficiently valuable to be worth the effort of conversion. We removed support for Rrst (it seems that not many people use it anymore), debugging code (a debug adapter would be better), legacy omni-completion (auto completion with nvim-cmp is better), and highlighting functions from .GlobalEnv (difficult to make compatible with tree-sitter + LSP highlighting).

We changed the default key binding to insert the assignment operator (<-) from an underscore (which was familiar to Emacs-ESS users) to Alt+- which is more convenient (but does not work on Vim). See the option assignment_keymap.

We replaced the options R_source and after_R_start with some more specific hooks and we can insert other hooks for Lua functions at other parts of the code under user request.

We added a keybinding for the pipe operator (|>). This defaults to <LocalLeader>, and is configurable with the option pipe_keymap.

We added awareness of .Rproj files (the project-level configuration files used by RStudio). This may, for example, change whether pipe_keymap inserts |> or %>% for a particular project. See the option rproj_prioritise for a full list of the behaviours which may be affected by .Rproj files, or to change whether they should affect things at all.

We removed the "echo" parameters from the functions that send code to R Console. Users can still set the value of source_args to define the arguments that will be passed to base::source() and include the argument echo=TRUE. Now, there is a new option to define how many lines can be sent directly to the R Console without saving the code in a temporary file to be sourced (max_lines_to_paste).

The options for displaying R documentation (nvimpager) are now: "split_h", "split_v", "tab", "float" (not implemented yet), and "no".

The options openpdf and openhtml were renamed as open_pdf and open_html, they now are strings and there with a minor change in how they behave.

The option nvim_wd was renamed as setwd and it now is a string and its default value is "no".

The option notmuxconf was renamed as config_tmux to avoid the negation of the negation notmuxconf=false or the even more awkward confirmation of the negation notmuxconf=true. The default value of config_tmux is true.

New features

There are two new commands:

• :RMapsDesc displays the list of key bindings followed by short descriptions.

• :RConfigShow displays the list of configuration options and their current values.

There is one new command to send the above-piped chain of commands. Its default key binding is <LocalLeader>sc.

There is a new option: auto_quit.

If you have colorout installed, and if you are not loading it in your ~/.Rprofile, it should be the development version. Reason: R.nvim calls the function colorout::isColorOut() which unduly enables the colorizing of output in the released version of colorout. This bug was fixed in this commit.

There are two new commands available to separate a file path into its different components.

The first command, sp, will take the file path under the cursor and break it down into its components, then surround it with the paste() function.

The second command, sh, will also break down the file path under the cursor into its components, but instead surround it with the here() function.

It's important to note that both functions require the nvim-treesitter plugin to be installed.

For example, if you have the following file path under the cursor:

read.csv("/home/user/Documents/file.csv")

Running the sp command will transform it into:

read.csv(paste("/home", "user", "Documents", "file.csv", sep = "/"))

Screenshots and videos

None yet. Tell us if you published a video presenting R.nvim features.

The communication between Neovim and R

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.

See also:

• cmp-r: nvim-cmp source using R.nvim as backend.

• languageserver: a language server for R.

• colorout: a package to colorize R's output.