1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/lifecycle-retired.R
3\name{stack}
4\alias{stack}
5\alias{global_frame}
6\alias{current_frame}
7\alias{ctxt_frame}
8\alias{call_frame}
9\alias{ctxt_depth}
10\alias{call_depth}
11\alias{ctxt_stack}
12\alias{call_stack}
13\title{Call stack information}
14\usage{
15global_frame()
16
17current_frame()
18
19ctxt_frame(n = 1)
20
21call_frame(n = 1, clean = TRUE)
22
23ctxt_depth()
24
25call_depth()
26
27ctxt_stack(n = NULL, trim = 0)
28
29call_stack(n = NULL, clean = TRUE)
30}
31\arguments{
32\item{n}{The number of frames to go back in the stack.}
33
34\item{clean}{Whether to post-process the call stack to clean
35non-standard frames. If \code{TRUE}, suboptimal call-stack entries by
36\code{\link[base:eval]{base::eval()}} will be cleaned up: the duplicate frame created by
37\code{eval()} is eliminated.}
38
39\item{trim}{The number of layers of intervening frames to trim off
40the stack. See \code{\link[=stack_trim]{stack_trim()}} and examples.}
41}
42\description{
43\Sexpr[results=rd, stage=render]{rlang:::lifecycle("deprecated")}
44
45The \code{eval_} and \code{call_} families of functions provide a replacement
46for the base R functions prefixed with \code{sys.} (which are all about
47the context stack), as well as for \code{\link[=parent.frame]{parent.frame()}} (which is the
48only base R function for querying the call stack). The context
49stack includes all R-level evaluation contexts. It is linear in
50terms of execution history but due to lazy evaluation it is
51potentially nonlinear in terms of call history. The call stack
52history, on the other hand, is homogenous.
53}
54\details{
55\code{ctxt_frame()} and \code{call_frame()} return a \code{frame} object
56containing the following fields: \code{expr} and \code{env} (call expression
57and evaluation environment), \code{pos} and \code{caller_pos} (position of
58current frame in the context stack and position of the caller), and
59\code{fun} (function of the current frame). \code{ctxt_stack()} and
60\code{call_stack()} return a list of all context or call frames on the
61stack. Finally, \code{ctxt_depth()} and \code{call_depth()} report the
62current context position or the number of calling frames on the
63stack.
64
65The base R functions take two sorts of arguments to indicate which
66frame to query: \code{which} and \code{n}. The \code{n} argument is
67straightforward: it's the number of frames to go down the stack,
68with \code{n = 1} referring to the current context. The \code{which} argument
69is more complicated and changes meaning for values lower than 1.
70For the sake of consistency, the rlang functions all take the
71same kind of argument \code{n}. This argument has a single meaning (the
72number of frames to go down the stack) and cannot be lower than 1.
73
74Note finally that \code{parent.frame(1)} corresponds to
75\code{call_frame(2)$env}, as \code{n = 1} always refers to the current
76frame. This makes the \verb{_frame()} and \verb{_stack()} functions
77consistent: \code{ctxt_frame(2)} is the same as \code{ctxt_stack()[[2]]}.
78Also, \code{ctxt_depth()} returns one more frame than
79\code{\link[base:sys.parent]{base::sys.nframe()}} because it counts the global frame. That is
80consistent with the \verb{_stack()} functions which return the global
81frame as well. This way, \code{call_stack(call_depth())} is the same as
82\code{global_frame()}.
83}
84\section{Life cycle}{
85
86
87These functions are soft-deprecated and replaced by \code{\link[=trace_back]{trace_back()}}.
88}
89
90\examples{
91# Expressions within arguments count as contexts
92identity(identity(ctxt_depth())) # returns 2
93
94# But they are not part of the call stack because arguments are
95# evaluated within the calling function (or the global environment
96# if called at top level)
97identity(identity(call_depth())) # returns 0
98
99# The context stacks includes all intervening execution frames. The
100# call stack doesn't:
101f <- function(x) identity(x)
102f(f(ctxt_stack()))
103f(f(call_stack()))
104
105g <- function(cmd) cmd()
106f(g(ctxt_stack))
107f(g(call_stack))
108
109# The rlang _stack() functions return a list of frame
110# objects. Use purrr::transpose() or index a field with
111# purrr::map()'s to extract a particular field from a stack:
112
113# stack <- f(f(call_stack()))
114# purrr::map(stack, "env")
115# purrr::transpose(stack)$expr
116
117# current_frame() is an alias for ctxt_frame(1)
118fn <- function() list(current = current_frame(), first = ctxt_frame(1))
119fn()
120
121# While current_frame() is the top of the stack, global_frame() is
122# the bottom:
123fn <- function() {
124  n <- ctxt_depth()
125  ctxt_frame(n)
126}
127identical(fn(), global_frame())
128
129
130# ctxt_stack() returns a stack with all intervening frames. You can
131# trim layers of intervening frames with the trim argument:
132identity(identity(ctxt_stack()))
133identity(identity(ctxt_stack(trim = 1)))
134
135# ctxt_stack() is called within fn() with intervening frames:
136fn <- function(trim) identity(identity(ctxt_stack(trim = trim)))
137fn(0)
138
139# We can trim the first layer of those:
140fn(1)
141
142# The outside intervening frames (at the fn() call site) are still
143# returned, but can be trimmed as well:
144identity(identity(fn(1)))
145identity(identity(fn(2)))
146
147g <- function(trim) identity(identity(fn(trim)))
148g(2)
149g(3)
150}
151\keyword{internal}
152