match_call: Match Closure Arguments To Formals

In brodieG/matchcall: Match Calls From Dynamic Stack

Description

Similar to match.call, but is designed specifically to match calls at varying depts from the dynamic call stack. Which call is matched is controlled by the n argument, which is analgous to the n argument for sys.parent. match_call also addresses some potentially unexpected behavior with match.call with calls involving dots (...) in corner cases.

Usage

match_call(n = 1L, dots = "expand", default.formals = FALSE,
  empty.formals = FALSE, user.formals = TRUE, definition = NULL)

Arguments

n	integer(1L) how many frames to look up the call stack, analogous to the n parameter for sys.parent.
dots	character(1L) "exclude": do not include dots, "include": include them, "expand": include and expand (note last two only include dots if there are actually args matched by dots)
default.formals	set to TRUE to include formals not specified in call though under no circumstances will it return ellipses even if you do something like function(a, ...=list(1, 2, 3)) which oddly R appears to tolerate in closure definitions.
empty.formals	set to TRUE to include formals that were not specified and do not have default values
user.formals	set to FALSE if you want to exclude arguments that the user specified; this should almost never be needed unless you specifically want to know what arguments are using default values (in which case you also be setting default.formals to TRUE)
definition	same as definition in match.call, though shouldn't be needed most of the time

Details

You can also use match.call to match arbitrary calls from the call stack, but it is simpler to do so using match_call, particularly when the call stack and the lexical stack are not the same. See examples for illustration of differences between match.call and match_call.

match_call will also include unspecified defaults and missing arguments if requested (see default.formals and empty.formals).

For a more detailed discussion of the exact nature of the dots corner case issues with match.call, see the vignette. Briefly: these crop up when there are multiple calls using dots involved.

Value

the parent call that led to the invocation of match_call()

Examples

# Compare `match.call` and `match_call`
fun1 <- function(a, b) {
  cat("**Matching Parent Call**\n")
  print(match.call())
  print(match_call())

  cat("\n**Matching Grand-Parent Call**\n")
  print(match.call(call=sys.call(sys.parent())))
  print(match_call(2))
}
fun2 <- function(c, d) fun1(a + 1, b - 1)
fun2(25, pi() + 3)

# Recover default formals
fun <- function(a, b, c=TRUE, ...) {
  match_call(default.formals=TRUE, dots="include")
}
fun(5, 6, x=list(1:10, FALSE))

# If Dynamic and Lexical Stacks not the same, we need to use `definition`
# param to `match.call`; `match_call` on the other hand works just fine

fun3a <- function(x) fun4a()
fun4a <- function() match_call(2)

fun3b <- function(x) fun4b()  # Note: fun4b defined outside fun3b
fun4b <- function() match.call(definition=fun3b, call=sys.call(sys.parent()))

fun3a(1 + 1)       # `match_call` works
fun3b(1 + 1)       # `match.call` also works, but only if we explicitly specify `definition`

brodieG/matchcall documentation built on May 13, 2019, 7:46 a.m.