R: Check that arguments are mutually exclusive

check_exclusive {rlang} | R Documentation

## Check that arguments are mutually exclusive

### Description

`check_exclusive()` checks that only one argument is supplied out of a set of mutually exclusive arguments. An informative error is thrown if multiple arguments are supplied.

### Usage

    check_exclusive(
      ...,
      .require = TRUE,
      .frame = caller_env(),
      .error_call = .frame
    )

### Arguments

`...` | Function arguments.
`.require` | Whether at least one argument must be supplied.
`.frame` | Environment where the arguments in `...` are defined.
`.error_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.

### Value

The supplied argument name as a string. If `.require` is `FALSE` and no argument is supplied, the empty string `""` is returned.

### Examples

    f <- function(x, y) {
      switch(
        check_exclusive(x, y),
        x = message("`x` was supplied."),
        y = message("`y` was supplied.")
      )
    }

    # Supplying zero or multiple arguments is forbidden
    try(f())
    try(f(NULL, NULL))

    # The user must supply one of the mutually exclusive arguments
    f(NULL)
    f(y = NULL)

    # With `.require` you can allow zero arguments
    f <- function(x, y) {
      switch(
        check_exclusive(x, y, .require = FALSE),
        x = message("`x` was supplied."),
        y = message("`y` was supplied."),
        message("No arguments were supplied")
      )
    }
    f()

[Package rlang version 1.0.2 Index]