languageserver: An implementation of the Language Server Protocol for R

languageserver is an implementation of the Microsoft’s Language Server Protocol for the language of R.

Installation
Language Clients
Services Implemented
Settings
FAQ

Installation

A few dependencies are required beforehand:

# On Debian, Ubuntu, etc.
apt install --assume-yes --no-install-recommends build-essential libcurl4-openssl-dev libssl-dev libxml2-dev libuv1-dev r-base

# On Fedora, Centos, etc.
dnf install --assumeyes --setopt=install_weak_deps=False @development-tools libcurl-devel libxml2-devel openssl-devel libuv-devel R

# On Alpine
apk add --no-cache curl-dev g++ gcc libxml2-dev linux-headers make R R-dev

languageserver is released on CRAN and can be easily installed by

install.packages("languageserver")

To try the latest features, install the daily development build from our r-universe repository:

install.packages("languageserver", repos = c(
    reditorsupport = "https://reditorsupport.r-universe.dev",
    getOption("repos")
))

Or install the latest development version from our GitHub repository:

# install.packages("remotes")
remotes::install_github("REditorSupport/languageserver")

Language Clients

The following editors are supported by installing the corresponding extensions:

VS Code: vscode-R
Atom: atom-ide-r
Sublime Text: R-IDE

NeoVim: NeoVim’s LSP client with settings

vim.lsp.config['r_language_server'] = {
    settings = {
        filetypes = { "r", "rmd" },
    },
}
vim.api.nvim_create_autocmd("FileType", {
    pattern = { "r", "rmd" },
    callback = function()
        vim.lsp.start(vim.lsp.config["r_language_server"])
    end,
}

or, if you use coc.nvim, you can do one of two things:

Install coc-r-lsp with:
```
:CocInstall coc-r-lsp
```

or install the languageserver package in R

install.packages("languageserver")
# or install the developement version
# remotes::install_github("REditorSupport/languageserver")

Then add the following to your Coc config:

"languageserver": {
    "R": {
        "command": "/usr/bin/R",
        "args" : [ "--no-echo", "-e", "languageserver::run()"],
        "filetypes" : ["r"]
    }
}

Emacs: eglot-mode (native LSP client)
```
(use-package ess :ensure t)
(add-hook 'ess-r-mode-hook 'eglot-ensure)
```
To check if it is working, open an R file, place the cursor on a line and run M-x ess-eval-line.
Emacs: lsp-mode
JupyterLab: jupyterlab-lsp
BBEdit: preconfigured in version 14.0 and later; see the BBEdit LSP support page for complete details.
Nova: R-Nova

Services Implemented

languageserver is still under active development, the following services have been implemented:

Inline values are a debugger-facing feature rather than normal editor annotations. When execution is paused, a compatible editor and debug adapter request variable lookup ranges from the language server, evaluate them in the selected stack frame, and render the resulting values beside the source. They have no visible effect when the client or R debug adapter does not request textDocument/inlineValue.

Settings

languageserver exposes the following settings via LSP configuration.

settings	default	description
`r.lsp.debug`	`false`	increase verbosity for debug purpose
`r.lsp.log_file`	`null`	file to log debug messages, fallback to stderr if empty
`r.lsp.diagnostics`	`true`	enable file diagnostics via lintr
`r.lsp.inlay_hints_minimum_arguments`	`2`	minimum supplied arguments before parameter-name inlay hints are shown
`r.lsp.inlay_hints_minimum_argument_length`	`2`	minimum argument-name length for an inlay hint, excluding an initial `.`
`r.lsp.rich_documentation`	`true`	rich documentation with enhanced markdown features
`r.lsp.snippet_support`	`true`	enable snippets in auto completion
`r.lsp.max_completions`	200	maximum number of completion items
`r.lsp.lint_cache`	`false`	toggle caching of lint results
`r.lsp.parse_delay`	`0.15`	seconds to debounce parsing after an edit
`r.lsp.diagnostics_delay`	`0.75`	seconds to debounce diagnostics after the current parse
`r.lsp.parse_cache_max_mb`	`64`	maximum memory used by cached document parse versions
`r.lsp.diagnostics_cache_max_mb`	`16`	maximum memory used by cached diagnostics
`r.lsp.index_mode`	`"auto"`	index R files in the complete workspace; use `"off"` to restore package-only loading
`r.lsp.index_include`	`"*/.R"`	glob or character vector of globs included in workspace indexing
`r.lsp.index_exclude`	common VCS, dependency, cache, and output directories	glob or character vector of globs excluded from workspace indexing
`r.lsp.index_max_files`	`10000`	maximum number of eligible R files discovered per workspace
`r.lsp.index_max_file_size_mb`	`2`	maximum size of a file included in the workspace index
`r.lsp.index_batch_size`	`20`	maximum number of shallow summaries built in one idle batch
`r.lsp.index_time_budget_ms`	`25`	approximate event-loop budget for each shallow-index batch
`r.lsp.index_persistent_cache`	`true`	persist validated shallow summaries in the user cache directory
`r.lsp.server_capabilities`	`{}`	override server capabilities defined in capabilities.R. See FAQ below.
`r.lsp.link_file_size_limit`	16384	maximum file size (in bytes) that supports document links

These settings could also specified in .Rprofile file via options(languageserver.<SETTING_NAME> = <VALUE>). For example,

options(languageserver.snippet_support = FALSE)

will turn off snippet support globally. LSP configuration settings are always overriden by options().

Project indexing is deliberately two-tiered. Package R/ files, open files, and the transitive dependencies of static source() or sys.source() calls receive full semantic parsing. Other scripts receive only a lightweight symbol and source-call summary, so they appear in workspace symbol search without polluting completion, definition, references, or rename in unrelated scripts. Static paths built from string literals, file.path(), and here::here() are recognized; project code is never executed to resolve a path.

FAQ

Linters

With lintr v2.0.0, the linters can be specified by creating the .lintr file at the project or home directory. Details can be found at lintr documentation.

Customizing server capabilities

Server capabilities are defined in capabilities.R. Users could override the capabilities by specifying the LSP configuration setting server_capabilities or options(languageserver.server_capabilities) in .Rprofile. For example, to turn off definitionProvider, one could either use LSP configuration

"r": {
    "lsp": {
        "server_capabilities": {
            "definitionProvider": false
        }
    }
}

or R options

options(
    languageserver.server_capabilities = list(
        definitionProvider = FALSE
    )
)

Customizing formatting style

The language server uses styler to perform code formatting. It uses styler::tidyverse_style(indent_by = options$tabSize) as the default style where options is the formatting options.

The formatting style can be customized by specifying languageserver.formatting_style option which is supposed to be a function that accepts an options argument mentioned above. You could consider to put the code in .Rprofile.

styler::tidyverse_style provides numerous arguments to customize the formatting behavior. For example, to make it only work at indention scope:

options(languageserver.formatting_style = function(options) {
    styler::tidyverse_style(scope = "indention", indent_by = options$tabSize)
})

To disable assignment operator fix (replacing = with <-):

options(languageserver.formatting_style = function(options) {
    style <- styler::tidyverse_style(indent_by = options$tabSize)
    style$token$force_assignment_op <- NULL
    style
})

To further customize the formatting style, please refer to Customizing styler.