check_dots_used {rlang}

Check that all dots have been used

Description

When ... arguments are passed to methods, it is assumed there method will match and use these arguments. If this isn't the case, this often indicates a programming error. Call check_dots_used() to fail with an error when unused arguments are detected.

Usage

check_dots_used(
  env = caller_env(),
  call = caller_env(),
  error = NULL,
  action = deprecated()
)

Arguments

env

Environment in which to look for ... and to set up handler.

call

The execution environment of a currently running function, e.g. caller_env(). The function will be mentioned in error messages as the source of the error. See the call argument of abort() for more information.

error

An optional error handler passed to try_fetch(). Use this e.g. to demote an error into a warning.

action

Details

In packages, document ... with this standard tag:

 @inheritParams rlang::args_dots_used

check_dots_used() implicitly calls on.exit() to check that all elements of ... have been used when the function exits. If you use on.exit() elsewhere in your function, make sure to use add = TRUE so that you don't override the handler set up by check_dots_used().

See Also

Other dots checking functions: check_dots_empty(), check_dots_unnamed()

Examples

f <- function(...) {
  check_dots_used()
  g(...)
}

g <- function(x, y, ...) {
  x + y
}
f(x = 1, y = 2)

try(f(x = 1, y = 2, z = 3))

try(f(x = 1, y = 2, 3, 4, 5))

# Use an `error` handler to handle the error differently.
# For instance to demote the error to a warning:
fn <- function(...) {
  check_dots_empty(
    error = function(cnd) {
      warning(cnd)
    }
  )
  "out"
}
fn()