R: Modify the arguments of a call

call_modify {rlang}

R Documentation

Modify the arguments of a call

Description

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

Usage

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.
`...`	Named or unnamed expressions (constants, names or calls) used to modify the call. Use `zap()` to remove arguments. These dots support tidy dots features. Empty arguments are allowed and 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

Prior to rlang 0.3.0, NULL was the sentinel for removing arguments. As of 0.3.0, zap() objects remove arguments and NULL simply adds an argument set to NULL. This breaking change allows the deletion sentinel to be distinct from valid argument values.
The .standardise argument is soft-deprecated as of rlang 0.3.0.
In rlang 0.2.0, lang_modify() was soft-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)
call_modify(call, x = quote(y))

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

# Add a new argument
call_modify(call, trim = 0.1)

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

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

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


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

call <- call_modify(call, ... = zap())
call


# 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)

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


# You can also modify quosures inplace:
f <- quo(matrix(bar))
call_modify(f, quote(foo))


# 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())

# 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")
call_modify(call, !!!args, .homonyms = "last")

[Package rlang version 0.3.2 Index]