Skip to contents

Argument matching

match.call2.Rd

Wraps base::match.call() with two additions.

  1. Argument n selects a call further up the call stack rather than the immediate caller.

  2. Argument defaults = TRUE inserts formal defaults for arguments the caller did not supply.

Usage

match.call2(
  n = 0L,
  definition = sys.function(sys.parent(n + 1L)),
  call = sys.call(sys.parent(n + 1L)),
  expand.dots = TRUE,
  envir = parent.frame(n + 2L),
  defaults = FALSE
)

Arguments

n

(Scalar integer: 0L)
How far up the call stack to match a call. n=0 is defined as the call above match.call2(). Values larger than the available call stack depth raise an error.

definition

(function: sys.function(sys.parent(n + 1L)))
The function whose call is being matched. By default, this is the function n frames above match.call2().

call

(call: sys.call(sys.parent(n + 1L)))
An unevaluated call to the function specified by definition. By default, this is the call n frames above match.call2().

expand.dots

(Scalar logical: c(TRUE, FALSE))
Whether arguments matching ... are expanded into the call as named arguments (TRUE), or kept grouped under a single ... slot (FALSE).

envir

(environment: parent.frame(n + 2L))
The environment used to look up ... when call contains a literal ... symbol. This applies, for example, when a wrapper forwards ... to definition. By default, this is the environment in which definition was called.

defaults

(Scalar logical: c(FALSE, TRUE))
Whether or not to include unspecified default arguments in the call. Formals without a default value are not inserted.

Value

An object of class call. When defaults = TRUE, formal arguments with defaults that the caller did not supply are inserted into the call as unevaluated expressions. Caller-supplied arguments retain their positions, and the inserted defaults are appended after them in formal order.

See also

base::match.call()

Examples

#----------------------------------------------------------------------------
# match.call2() examples
#----------------------------------------------------------------------------
library(bkbase)

# Basic usage: capture the matched call from within a function.
fit <- function(x, y, method = "ols", tol = 1e-8) {
  match.call2()
}
fit(1:5, 6:10)
#> fit(x = 1:5, y = 6:10)

# defaults = TRUE inserts unevaluated formal defaults for arguments the
# caller did not supply, producing a self-describing call useful for
# logging or reproducing results.
fit2 <- function(x, y, method = "ols", tol = 1e-8) {
  match.call2(defaults = TRUE)
}
fit2(1:5, 6:10)
#> fit2(x = 1:5, y = 6:10, method = "ols", tol = 1e-08)
fit2(1:5, 6:10, method = "ridge")
#> fit2(x = 1:5, y = 6:10, method = "ridge", tol = 1e-08)

# n > 0 reaches further up the call stack, so a helper can inspect how
# its caller was invoked.
log_caller <- function() match.call2(n = 1)
wrapper <- function(a, b = 2) log_caller()
wrapper(a = 10)
#> wrapper(a = 10)

# expand.dots = FALSE keeps the ... arguments grouped under one slot.
inspect <- function(x, ...) match.call2(expand.dots = FALSE)
inspect(x = 1, extra1 = "a", extra2 = "b")
#> inspect(x = 1, ... = pairlist(extra1 = "a", extra2 = "b"))