1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/eval.R
3\name{invoke}
4\alias{invoke}
5\title{Invoke a function with a list of arguments}
6\usage{
7invoke(.fn, .args = list(), ..., .env = caller_env(), .bury = c(".fn", ""))
8}
9\arguments{
10\item{.fn}{A function to invoke. Can be a function object or the
11name of a function in scope of \code{.env}.}
12
13\item{.args, ...}{List of arguments (possibly named) to be passed to
14\code{.fn}.}
15
16\item{.env}{The environment in which to call \code{.fn}.}
17
18\item{.bury}{A character vector of length 2. The first string
19specifies which name should the function have in the call
20recorded in the evaluation stack. The second string specifies a
21prefix for the argument names. Set \code{.bury} to \code{NULL} if you
22prefer to inline the function and its arguments in the call.}
23}
24\description{
25\Sexpr[results=rd, stage=render]{rlang:::lifecycle("soft-deprecated")}
26
27Normally, you invoke a R function by typing arguments manually. A
28powerful alternative is to call a function with a list of arguments
29assembled programmatically. This is the purpose of \code{invoke()}.
30}
31\details{
32Technically, \code{invoke()} is basically a version of \code{\link[base:do.call]{base::do.call()}}
33that creates cleaner call traces because it does not inline the
34function and the arguments in the call (see examples). To achieve
35this, \code{invoke()} creates a child environment of \code{.env} with \code{.fn}
36and all arguments bound to new symbols (see \code{\link[=env_bury]{env_bury()}}). It then
37uses the same strategy as \code{\link[=eval_bare]{eval_bare()}} to evaluate with minimal
38noise.
39}
40\section{Life cycle}{
41
42
43\code{invoke()} is soft-deprecated in favour of \code{\link[=exec]{exec()}}. Now that we
44understand better the interaction between unquoting and dots
45capture, we can take a simpler approach in \code{exec()}.
46
47If you need finer control over the generated call, you should construct
48an environment and call yourself, manually burying large objects
49or complex expressions.
50}
51
52\examples{
53# invoke() has the same purpose as do.call():
54invoke(paste, letters)
55
56# But it creates much cleaner calls:
57invoke(call_inspect, mtcars)
58
59# and stacktraces:
60fn <- function(...) sys.calls()
61invoke(fn, list(mtcars))
62
63# Compare to do.call():
64do.call(call_inspect, mtcars)
65do.call(fn, list(mtcars))
66
67
68# Specify the function name either by supplying a string
69# identifying the function (it should be visible in .env):
70invoke("call_inspect", letters)
71
72# Or by changing the .bury argument, with which you can also change
73# the argument prefix:
74invoke(call_inspect, mtcars, .bury = c("inspect!", "col"))
75}
76\keyword{internal}
77