search

R-nvim / R.nvim

Neovim plugin to edit R files
GNU General Public License v3.0
181 stars 19 forks source link

readme

GitHub Release Selene linter check

R.nvim

R.nvim adds R support to Neovim, including:

Installation

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()
        ---@type RConfigUserOpts
        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.

Autocompletion

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

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", "csv" },
            highlight = { enable = true },
        })
    end
},

Usage

Please see the documentation for instructions on usage. For a complete list of keymaps, see the output of :RMapsDesc.

Lifecycle

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.

Transitioning from Nvim-R

Removed features:

Changes:

New features

New commands

New keybindings

New options

Screenshots and videos

None yet! Please let us know if you publish a video presenting R.nvim features 😃

Troubleshooting

How R.nvim communicates with your R session

The diagram below shows how the communication between Neovim and R works. Neovim-R communication

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:

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: