rlang: call_modify – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

call_modify

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.
`...`	<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)
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")

rlang

Functions for Base Types and Core R and 'Tidyverse' Features

v0.4.11

MIT + file LICENSE

Authors

Lionel Henry [aut, cre], Hadley Wickham [aut], mikefc [cph] (Hash implementation based on Mike's xxhashlite), Yann Collet [cph] (Author of the embedded xxHash library), RStudio [cph]

Initial release