Configuration
Everything that changes what ry reports lives in one ry.toml, so the editor, the command line, and
CI always agree. This is every key, with its default:
[check]typing = false # report type errorsstrict = false # report unknown types and untyped parameters; implies typinginline-annotations = true # type inline annotations such as `x: integer <- 1L`object-systems = true # allow S4, R6 and Reference Classes; false makes each definition an errorprelude = true # put the standard library in scope by bare name; false requires `std::`unused = true # report values that are never readmaybe-undefined = false # report reads some path reaches before a writeexclude = [] # gitignore-style patterns that ry check skips
[lint] # each takes "off", "warn", "error", or "default"assignment-operator = "warn" # `=` used for assignmentboolean-shorthand = "warn" # T or F instead of TRUE or FALSEtrailing-comma = "warn" # a comma after a call's last argumentequals-na = "warn" # x == NA, which is always NAvector-logic = "warn" # & or | in an if or while conditionlength-sequence = "warn" # 1:length(x), which counts down when x is emptyclass-equals = "warn" # class(x) == "name" instead of inherits()unreachable-code = "warn" # statements after return(), stop(), break or nextsprintf-arguments = "warn" # a sprintf() format that wants more or fewer valueslength-test = "warn" # length(x == y) instead of length(x) == yredundant-return = "off" # return() as a function's last expressioncommented-code = "off" # a comment that is commented-out codeduplicate-argument = "off" # the same argument name twice in one callany-is-na = "off" # any(is.na(x)) instead of anyNA(x)paste-sep = "off" # paste(..., sep = "") instead of paste0(...)lengths = "off" # sapply(x, length) instead of lengths(x)literal-coercion = "off" # as.integer(1) instead of 1Lredundant-equals = "off" # x == TRUE instead of xsingle-quotes = "off" # 'text' instead of "text"testthat-expectation = "off" # expect_equal(x, NULL) instead of expect_null(x)condition-message = "off" # stop(paste0(...)) instead of stop(...)comparison-negation = "off" # !(x == y) instead of x != youter-negation = "off" # all(!x) instead of !any(x)fixed-regex = "off" # a regex with no regex syntax and no fixed = TRUEwhich-grepl = "off" # which(grepl(...)) instead of grep(...)length-levels = "off" # length(levels(x)) instead of nlevels(x)browser-call = "off" # a browser() call left in the codenumeric-leading-zero = "off" # .5 instead of 0.5implicit-assignment = "off" # an assignment inside an if or while conditionwhile-true = "off" # while (TRUE) instead of repeatscalar-in = "off" # x %in% 1 instead of x == 1order-subset = "off" # x[order(x)] instead of sort(x)matrix-apply = "off" # apply(x, 1, sum) instead of rowSums(x)empty-assignment = "off" # x <- {} instead of x <- NULLunnecessary-lambda = "off" # lapply(x, function(y) f(y)) instead of lapply(x, f)yoda-test = "off" # expect_equal(2, x) instead of expect_equal(x, 2)nzchar = "off" # nchar(x) == 0 instead of !nzchar(x)sample-int = "off" # sample(1:n, k) instead of sample.int(n, k)unnecessary-concatenation = "off" # c("a") or c() around a single constantline-length = "off" # a line longer than max-line-length charactersmax-line-length = 80 # the limit line-length checksunused-parameter = "off" # a parameter the body never readsunused-import = "off" # a NAMESPACE importFrom nothing usesshadows-builtin = "off" # a top-level name that hides a base functionshadows-namespace = "off" # a top-level name that hides another export# naming-style = "snake_case" # or "camelCase"; unset means not checkedobject-system = "warn" # a class defined with S4, R6 or Reference Classesdata-table = "off" # a call that creates a data.table
[format]indent-width = 2line-ending = "auto" # keep the file's own; or "lf", "cr-lf"
[console]highlight = true # color the input of `ry run` and `ry R`'s console[console.colors] # override a style, such as keyword = "bright-blue bold"The diagnostic codes page explains each finding. strict turns on type errors
too and raises unresolved names to errors. A # typing: off, on, or strict comment in a file
overrides both keys for that file, and may end in a note such as # typing: off # generated code.
Which file applies
Section titled “Which file applies”ry walks up from the file you check, or from the editor’s workspace folder, and uses the first
ry.toml it finds. Nothing is merged, and there is no home-directory file or environment variable.
Each path you pass on the command line finds its own file, so two paths can use two different
configurations. A .. in a path is resolved before the search, so project/ry.toml does not apply
to project/../outside.R. The language server re-reads the file whenever it changes, and deleting
it falls back to an ancestor’s file or to the defaults. A roughly.toml from before the rename is
still read.
The project root is a separate question: it decides which files see each other’s definitions. It is
the nearest directory with a ry.toml or a DESCRIPTION. Without one, it is the directory you
named, or the parent of R/ for a file directly inside R/, or else the file’s own directory. In
the editor it is the first workspace folder.
A lintr .lintr file
Section titled “A lintr .lintr file”A package set up for lintr keeps its lint choices without a ry.toml. ry reads the linters field
of the .lintr at the project root, the nearest directory with a ry.toml, a roughly.toml or a
DESCRIPTION, and fills every lint level that ry.toml leaves unset:
linters: linters_with_defaults( line_length_linter(120), commented_code_linter = NULL, any_is_na_linter() )A linter called in the field turns on the ry lints that report the same thing, so this file turns
on any-is-na and line-length with a limit of 120. A linter set to NULL turns its lints off.
linters_with_defaults() also turns on lintr’s defaults that are off in ry: commented-code,
line-length at 80, naming-style in snake_case, redundant-return and single-quotes. A setting
that asks for the opposite of a ry lint turns it off: return_linter(return_style = "explicit") turns
off redundant-return, and quotes_linter("'") turns off single-quotes.
object_name_linter(styles = "camelCase") sets camelCase, and a list of styles that allows both
camelCase and snake_case leaves naming-style unset. ry warns once for each linter it has no lint for,
except lintr’s whitespace and layout linters, which ry format covers, and a .lintr that is not
UTF-8 text is ignored with a warning. The other fields, such as exclusions, are not read. The
language server re-reads a .lintr in the workspace folder when it changes.
inline-annotations
Section titled “inline-annotations”Inline annotations, such as count: integer <- 0L and function(x: integer) -> integer, are on by
default. R itself cannot run them, so a project that must stay runnable by R can set
inline-annotations = false. Inline annotations then type nothing, each one is reported as an
inline-annotation warning, and a #: comment on the same statement applies alone. For as long as
the setting is off, ry check warns about it once per run, and the language server once whenever it
loads ry.toml:
! inline type annotations are turned off (`[check] inline-annotations = false`), so ry does not check them and reports each one it findsobject-systems
Section titled “object-systems”S4, R6 and Reference Classes keep working, but ry recommends
records and tagged unions, which it checks statically, so each
class or method definition gets an object-system warning. Set [lint] object-system = "off" to
silence it. A project that wants none of these classes sets object-systems = false, and every
definition becomes an error, whatever the lint level says. Only definitions are reported, so a call
to new() on a class from another package is not.
ry run and its console, on ry’s runtime, enforce the setting too. A call to
setClass, setClassUnion, setGeneric, setMethod, setValidity, setRefClass or R6Class
from your own code stops with the same message as the lint:
Error in setClass("P", representation(x = "numeric")) : S4 classes are turned off in this project (`[check] object-systems = false`), so `setClass` cannot define an S4 class. Use a record or a tagged union insteadExecution haltedYour own code means code that runs at the top level of a script or the console, or inside a
function defined there. Code inside a package, installed or loaded with ry load, may still define
classes, so packages such as stats4 keep loading. The runtime recognizes the call by name
(setClass(...) or methods::setClass(...)), so a renamed alias such as f <- setClass is not
caught. GNU R (ry R) does not enforce the setting.
prelude
Section titled “prelude”ry’s standard library lives in the namespace std. The prelude, on by default,
also puts every function in scope by its bare name, so List.map and std::List.map are the same
function. A project that wants every use of the library spelled out sets prelude = false, and a
bare name is then unbound unless the project defines it itself:
unresolved
! `List.map` is in ry's standard library, which `[check] prelude = false` keeps out of scope. Write `std::List.map`. --[a.R:1:6] 1 | x <- List.map(list(1L, 2L), function(v) v + 1L) | ^^^^^^^^ help: Change to `std::List.map` (`ry check --fix --unsafe-fixes` applies it)The types Result, Dict, Set and List stay in scope either way. ry run and its console
follow the setting too: with the prelude off, ry’s runtime does not attach package:std, so a bare
List.map fails there as well, while std::List.map works. GNU R (ry R) has no standard library
at all.
exclude
Section titled “exclude”Patterns follow gitignore rules and are anchored at the directory holding ry.toml, so
exclude = ["scripts/", "**/generated"] skips that subtree and any generated directory.
- Excluded files drop out of analysis, not just out of the report, so names they define become unresolved everywhere else. Exclude only code nothing else calls into.
- A file you name on the command line, or open in the editor, is still analyzed.
ry fmtignores the key.renv/,packrat/,revdep/,.Rproj.user/,.Rcheck/, and whatever.gitignorelists are always skipped, because they hold dependencies and build output rather than your code.
console
Section titled “console”The console of ry run and ry R colors your input as you type, from the same syntax tree the
language server colors. highlight = false turns that off, and so does a non-empty NO_COLOR
environment variable, which also leaves the completion menu and hints without color. The bracket
at the cursor, or the one just before it, is shown reversed with its partner, and a closing
bracket with no opener is red.
The default colors use only the eight basic ANSI hues that read on both light and dark
backgrounds, so your terminal’s theme picks the exact shades. [console.colors] overrides a
style by name:
[console.colors]keyword = "bright-blue bold"comment = "dim"string = "none"| Name | Default | Colors |
|---|---|---|
keyword |
magenta bold |
if, function, in |
constant |
magenta |
TRUE, NULL, NA_integer_, Inf |
number |
cyan |
1L, 0x1F, 1e-3, 2i |
string |
green |
"a", r"(raw)" |
comment |
dim italic |
# note |
annotation |
cyan italic |
#: comments and inline types such as : integer |
operator |
bold |
<-, ->, |>, %in%, = as assignment |
function |
blue |
the f of f(x) or x$f(), and a name bound to a function |
namespace |
blue italic |
stats:: and base::: |
parameter |
italic |
parameters, and named arguments such as the n of f(n = 1) |
property |
none |
record fields, x$field and x@slot |
tag |
magenta |
:Circle |
quoted-name |
underline |
`my var` |
error |
red bold underline |
a closing bracket with no opener, an unreadable token |
matching-bracket |
reverse |
the bracket at the cursor and its partner |
A style is a space-separated list of words: at most one color (black, red, green, yellow,
blue, magenta, cyan, white, each also as bright-red and so on, or default), and any of
bold, dim, italic, underline and reverse. none is the plain style. An unknown name or
word is an error that names the line in ry.toml.
Mistakes in ry.toml
Section titled “Mistakes in ry.toml”An unknown or misplaced key is a warning, and the rest of the file still loads, so a configuration
written for a newer ry still works with an older one. The cost is that a typo does not fail CI: with
typng = true, ry check leaves type checking off, exits 0 on clean code, and only prints this:
! ignoring unknown config key `check.typng`. Check the spelling, or update ryInvalid TOML, a value of the wrong type, or an invalid exclude pattern is an error: ry check
exits with status 2, and the language server keeps the last good configuration and marks the line
in ry.toml.
The older top-level keys case and spaces still work, as naming-style and indent-width.
Editor settings
Section titled “Editor settings”Editor settings only say how to start the server. The server ignores any configuration the editor sends.
In VS Code, the extension uses, in order, the SERVER_PATH environment variable, ry.path, its
bundled binary, and ry on your PATH. A change takes effect after ry: Restart Server.
{ "ry.path": "/usr/local/bin/ry", "ry.args": ["server"]}In Zed, set the path under lsp.ry. Zed highlights R with tree-sitter, which treats a #:
annotation as a plain comment, so turn on semantic tokens to color annotations:
{ "lsp": { "ry": { "binary": { "path": "/usr/local/bin/ry" } } }, "languages": { "R": { "semantic_tokens": "combined" } }}