Modify the arguments of a call

If you are working with a user-supplied call, make sure the arguments are standardised with call_standardise() before modifying the call.

call_modify(
  .call,
  ...,
  .homonyms = c("keep", "first", "last", "error"),
  .standardise = NULL,
  .env = caller_env()
)

Arguments

.call	Can be a call, a formula quoting a call in the right-hand side, or a frame object from which to extract the call expression.
...	<dynamic> Named or unnamed expressions (constants, names or calls) used to modify the call. Use zap() to remove arguments. Empty arguments are preserved.
.homonyms	How to treat arguments with the same name. The default, "keep", preserves these arguments. Set .homonyms to "first" to only keep the first occurrences, to "last" to keep the last occurrences, and to "error" to raise an informative error and indicate what arguments have duplicated names.
.standardise, .env	Soft-deprecated as of rlang 0.3.0. Please call call_standardise() manually.

Value

A quosure if .call is a quosure, a call otherwise.

Life cycle

• The .standardise argument is deprecated as of rlang 0.3.0.

• In rlang 0.2.0, lang_modify() was deprecated and renamed to call_modify(). See lifecycle section in call2() for more about this change.

Examples

call <- quote(mean(x, na.rm = TRUE))

# Modify an existing argument
call_modify(call, na.rm = FALSE)
#> mean(x, na.rm = FALSE)
call_modify(call, x = quote(y))
#> mean(x, na.rm = TRUE, x = y)

# Remove an argument
call_modify(call, na.rm = zap())
#> mean(x)

# Add a new argument
call_modify(call, trim = 0.1)
#> mean(x, na.rm = TRUE, trim = 0.1)

# Add an explicit missing argument:
call_modify(call, na.rm = )
#> mean(x, na.rm = )

# Supply a list of new arguments with `!!!`
newargs <- list(na.rm = NULL, trim = 0.1)
call <- call_modify(call, !!!newargs)
call
#> mean(x, na.rm = NULL, trim = 0.1)

# Remove multiple arguments by splicing zaps:
newargs <- rep_named(c("na.rm", "trim"), list(zap()))
call <- call_modify(call, !!!newargs)
call
#> mean(x)


# Modify the `...` arguments as if it were a named argument:
call <- call_modify(call, ... = )
call
#> mean(x, ...)

call <- call_modify(call, ... = zap())
call
#> mean(x)


# When you're working with a user-supplied call, standardise it
# beforehand because it might contain unmatched arguments:
user_call <- quote(matrix(x, nc = 3))
call_modify(user_call, ncol = 1)
#> matrix(x, nc = 3, ncol = 1)

# Standardising applies the usual argument matching rules:
user_call <- call_standardise(user_call)
user_call
#> matrix(data = x, ncol = 3)
call_modify(user_call, ncol = 1)
#> matrix(data = x, ncol = 1)


# You can also modify quosures inplace:
f <- quo(matrix(bar))
call_modify(f, quote(foo))
#> <quosure>
#> expr: ^matrix(bar, foo)
#> env:  0x55ac98247778


# By default, arguments with the same name are kept. This has
# subtle implications, for instance you can move an argument to
# last position by removing it and remapping it:
call <- quote(foo(bar = , baz))
call_modify(call, bar = NULL, bar = missing_arg())
#> foo(bar = , baz)

# You can also choose to keep only the first or last homonym
# arguments:
args <-  list(bar = NULL, bar = missing_arg())
call_modify(call, !!!args, .homonyms = "first")
#> foo(bar = NULL, baz)
call_modify(call, !!!args, .homonyms = "last")
#> foo(bar = , baz)