Skip to contents

Is an Argument a Symbol?

Source: R/assertions.R
assert_symbol.Rd

Checks if an argument is a symbol

Usage

assert_symbol(
  arg,
  optional = FALSE,
  arg_name = gsub("^enexpr\\((.*)\\)$", "\\1", rlang::caller_arg(arg)),
  message = NULL,
  class = "assert_symbol",
  call = parent.frame()
)

Arguments

arg

A function argument to be checked. Must be a symbol. See examples.

optional

Is the checked argument optional? If set to FALSE and arg is NULL then an error is thrown.

arg_name

By default the expression specified for arg is used. If it is of the form enexpr(<argument name>), the enexpr() part is removed. For example if arg = enexpr(filter_add) is specified, arg_name defaults to "filter_add"

message

string passed to cli::cli_abort(message). When NULL, default messaging is used (see examples for default messages). "{arg_name}" can be used in messaging.

class

Subclass of the condition.

call

The execution environment of a currently running function, e.g. call = caller_env(). The corresponding function call is retrieved and mentioned in error messages as the source of the error.

You only need to supply call when throwing a condition from a helper function which wouldn't be relevant to mention in the message.

Can also be NULL or a defused function call to respectively not display any call or hard-code a code to display.

For more information about error calls, see Including function calls in error messages.

Value

The function throws an error if arg is not a symbol and returns the input invisibly otherwise.

See also

Checks for valid input and returns warning or errors messages: assert_atomic_vector(), assert_character_scalar(), assert_character_vector(), assert_data_frame(), assert_date_vector(), assert_expr(), assert_expr_list(), assert_filter_cond(), assert_function(), assert_integer_scalar(), assert_list_element(), assert_list_of(), assert_logical_scalar(), assert_named(), assert_numeric_vector(), assert_one_to_one(), assert_param_does_not_exist(), assert_s3_class(), assert_same_type(), assert_unit(), assert_vars(), assert_varval_list()

Examples

library(dplyr, warn.conflicts = FALSE)
library(rlang)
dm <- dplyr::tribble(
  ~DOMAIN,      ~USUBJID,
  "DM",    "01-701-1015",
  "DM",    "01-701-1016",
)
example_fun <- function(dat, var) {
  var <- assert_symbol(enexpr(var))
  select(dat, !!var)
}

example_fun(dm, USUBJID)
#> # A tibble: 2 × 1
#>   USUBJID    
#>   <chr>      
#> 1 01-701-1015
#> 2 01-701-1016

try(example_fun(dm))
#> Error in example_fun(dm) : 
#>   Argument `var` must be a <symbol>, but is missing.

try(example_fun(dm, "USUBJID"))
#> Error in example_fun(dm, "USUBJID") : 
#>   Argument `var` must be a <symbol>, but is a string.

try(example_fun(dm, toupper(PARAMCD)))
#> Error in example_fun(dm, toupper(PARAMCD)) : 
#>   Argument `var` must be a <symbol>, but is a call.