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