Do attribute assignment operators need to be declared in NAMESPACE? How?

Question

I have a package with a function foo which uses rlang::fn_fmls() and rlang::fn_fmls()<-:

#' @importFrom rlang fn_fmls missing_arg
foo <- function(x) {
  args <- rlang::fn_fmls(x)
  args <- c(args, bar = rlang::missing_arg())
  rlang::fn_fmls(x) <- args

  return(x)
}

Using roxygen2, I obviously need to document this function with an @importFrom rlang ... in order to get those functions declared in my NAMESPACE. However, does the inclusion of fn_flms there also handle the declaration of fn_fmls<-? Or does it also need to be included separately? If so, how? @importFrom rlang fn_fmls<-? "fn_fmls()<-"?

Aldridge

Answer 1

fn_fmls<- is an entirely separate function, an example of what is a called a replacement function, which you can read more about at the link. The gist is it must take the form function_name<-, and always returns a modified version of its first argument.

We can see in the rlang documentation that fn_fmls<- takes two arguments, fn and value. The function is used to replace the formal arguments of fn with value. Using a very simple example, if we only import fn_fmls, we get:

#' @importFrom rlang fn_fmls
foo <- function(values) {
  fn <- function(a = 1, b = 2) A + B
  fn_fmls(fn) <- values
  fn()
}

foo(list(A = 10, B = 20))
#> Error in fn_fmls(fn) <- values : could not find function "fn_fmls<-"

Instead, if we import fn_fmls<-, we get:

#' @importFrom rlang `fn_fmls<-`
foo <- function(values) {
  fn <- function(a = 1, b = 2) A + B
  fn_fmls(fn) <- values
  fn()
}

foo(list(A = 10, B = 20))
#> [1] 30

Note that we didn't have to import fn_fmls. This is because again, the similar naming is just a convention of convenience, since fn_fmls is a function to retrieve formal arguments of a function, it makes logical sense to name a function to replace formal arguments of a function fn_fmls<-, since it will be written as fn_fmls(fn) <- value.

Potts