By Example

A collection of short, self-contained recipes for common Jarl tasks in the terminal.

Lint a file

test.R

any(is.na(x))
1:nrow(data)

Terminal

$> jarl check test.R

warning: any_is_na
 --> test.R:1:1
  |
1 | any(is.na(x))
  | ------------- `any(is.na(...))` is inefficient.
  |
  = help: Use `anyNA(...)` instead.

warning: seq
 --> test.R:2:1
  |
2 | 1:nrow(data)
  | ------------ `1:nrow(...)` can produce unexpected results when the right-hand side is 0.
  |
  = help: Use `seq_len(nrow(...))` instead.

Found 2 errors.
2 fixable with the `--fix` option.

Lint a directory

Terminal

$> jarl check .

This recursively checks all .R, .Rmd, .rmd, and .qmd files starting from the current directory.

Fix violations automatically

test.R

any(is.na(x))
if (all.equal(x, y)) {
  print("x and y are equal")
}

Terminal

$> jarl check test.R --fix

test.R (after fix)

anyNA(x)
if (all.equal(x, y)) {
  print("x and y are equal")
}

Only safe fixes are applied by default. To also apply unsafe fixes:

Terminal

$> jarl check test.R --fix --unsafe-fixes

test.R (after unsafe fixes)

anyNA(x)
if (isTRUE(all.equal(x, y))) {
  print("x and y are equal")
}

Select or ignore specific rules

test.R

any(is.na(x))
1:nrow(data)
any(duplicated(x))

Terminal

# Note that there must be no space between commas!
$> jarl check test.R --select any_is_na,any_duplicated

warning: any_is_na
 --> test.R:1:1
  |
1 | any(is.na(x))
  | ------------- `any(is.na(...))` is inefficient.
  |
  = help: Use `anyNA(...)` instead.

warning: any_duplicated
 --> test.R:3:1
  |
3 | any(duplicated(x))
  | ------------------ `any(duplicated(...))` is inefficient.
  |
  = help: Use `anyDuplicated(...) > 0` instead.

Only the any_is_na and any_duplicated rules are applied, seq is not reported.

You can also select by family:

Terminal

$> jarl check test.R --select PERF

Or ignore specific rules:

Terminal

$> jarl check test.R --ignore seq

See Rules for all rule families.

Configure rules in `jarl.toml`

jarl.toml

[lint]
select = ["PERF", "length_test"]
ignore = ["any_duplicated"]

Terminal

$> jarl check .

CLI arguments always override the config file. See Configuration file for all options.

Show diagnostics in a more concise way

test.R

any(is.na(x))
1:nrow(data)

Terminal

$> jarl check test.R --output-format concise

test.R [1:1] any_is_na `any(is.na(...))` is inefficient. Use `anyNA(...)` instead.
test.R [2:1] seq `1:nrow(...)` can be wrong if the RHS is 0. Use `seq_len(nrow((...))` instead.

Found 2 errors.
2 fixable with the `--fix` option.

See CLI reference for all possible values of --output-format.

Suppress a diagnostic with a comment

test.R

# jarl-ignore any_is_na: false positive in this context
any(is.na(x))

Terminal

$> jarl check test.R

No violations found.

For details on range, file, and chunk comments, see Suppression comments.

Auto-insert suppression comments

test.R

any(is.na(x))

Terminal

$> jarl check test.R --add-jarl-ignore="remove this when bug xyz is fixed"

test.R (after)

# jarl-ignore any_is_na: remove this when bug xyz is fixed
any(is.na(x))

You can also use --add-jarl-ignore without a value to insert a default <reason> placeholder.

Show violation statistics

test.R

any(is.na(x))
1:nrow(data)
NA %in% y

Terminal

$> jarl check test.R --statistics

    2 [*] any_is_na
    1 [*] seq

Rules with `[*]` have an automatic fix.

Lint only R Markdown / Quarto files

Terminal

$> jarl check **/*.{Rmd,rmd,qmd}

Or in jarl.toml:

jarl.toml

[lint]
include = ["**/*.{Rmd,rmd,qmd}"]

See R Markdown & Quarto for limitations and details.

Set a minimum R version

Some rules depend on the R version. Passing --min-r-version x.y tells Jarl that the project runs with R version x.y or later. Therefore, Jarl knows that it can apply rules that were implemented before x.y.

For example, the grepv rule is only valid for R >= 4.5.0.

test.R

grep("on", c("hi there", "bonjour"), value = TRUE)

Terminal

# Doesn't show anything because the user might be using R < 4.5.0
$> jarl check test.R --min-r-version 4.3

# Shows the diagnostic because the user runs R >= 4.5.0
$> jarl check test.R --min-r-version 4.5

warning: grepv
 --> test.R:1:1
  |
1 | grep("on", c("hi there", "bonjour"), value = TRUE)
  | -------------------------------------------------- `grep(..., value = TRUE)` can be simplified.
  |
  = help: Use `grepv(...)` instead.

Found 1 error.
1 fixable with the `--fix` option.

See R versions for more.