r-statistics.co by Selva Prabhakaran

About

R Execution Stack: sys.call(), parent.frame() & Call Stack Internals

Every time you call a function in R, it gets pushed onto the call stack. R provides sys.call(), sys.frame(), parent.frame(), and sys.nframe() to inspect this stack at runtime — essential for metaprogramming and advanced debugging.

These functions are rarely needed in everyday R code, but they power many internal mechanisms: how tryCatch() finds handlers, how debug() walks through code, and how packages like rlang build their error reporting.

The Call Stack

When function A calls function B, which calls function C, R maintains a stack:

show_stack <- function() { cat("Stack depth:", sys.nframe(), "\n") cat("Call at frame 1:", deparse(sys.call(1)), "\n") } wrapper <- function() { show_stack() } wrapper()


  






sys.nframe(): How Deep Are We?





  


    
depth_test <- function(label) {
  cat(sprintf("%s: depth = %d\n", label, sys.nframe()))
}

level1 <- function() {
  depth_test("level1")
  level2()
}

level2 <- function() {
  depth_test("level2")
  level3()
}

level3 <- function() {
  depth_test("level3")
}

level1()


    


      

      

    


    


  






sys.call(): What Was Called?



sys.call(n) returns the call expression at frame n on the stack:





  


    
inspect_calls <- function() {
  n <- sys.nframe()
  cat("Total frames:", n, "\n")
  for (i in 1:n) {
    cat(sprintf("  Frame %d: %s\n", i, deparse(sys.call(i))))
  }
}

outer_fn <- function(x) {
  inner_fn(x + 1)
}

inner_fn <- function(y) {
  inspect_calls()
}

outer_fn(10)


    


      

      

    


    


  






sys.frame(): Get the Environment



sys.frame(n) returns the execution environment at frame n:





  


    
peek_at_caller <- function() {
  caller_env <- sys.frame(-1)  # -1 = parent frame
  cat("Caller's variables:", paste(ls(caller_env), collapse = ", "), "\n")
}

my_function <- function() {
  secret <- "hidden_value"
  local_data <- 1:5
  peek_at_caller()
}

my_function()


    


      

      

    


    


  






parent.frame(): The Caller's Environment



parent.frame() is shorthand for sys.frame(-1) — it gives you the environment of the function that called you:





  


    
# Useful for functions that need to evaluate in the caller's context
eval_in_caller <- function(expr_text) {
  expr <- parse(text = expr_text)
  eval(expr, envir = parent.frame())
}

x <- 100
y <- 200
result <- eval_in_caller("x + y")
cat("Evaluated in caller's env:", result, "\n")


    


      

      

    


    


  








  


    
# Real-world use: match.arg evaluates in the caller's context
my_plot <- function(type = c("line", "bar", "scatter")) {
  type <- match.arg(type)
  cat("Plot type:", type, "\n")
}

my_plot()         # uses default: "line"
my_plot("bar")    # exact match
my_plot("s")      # partial match: "scatter"


    


      

      

    


    


  






Practical Example: Custom Error Messages





  


    
# Use sys.call to generate informative error messages
check_positive <- function(x) {
  if (any(x <= 0)) {
    fn_call <- deparse(sys.call(-1))  # Caller's call
    stop(sprintf("In %s: all values must be positive, got: %s",
                 fn_call, paste(x[x <= 0], collapse = ", ")),
         call. = FALSE)
  }
}

safe_sqrt <- function(values) {
  check_positive(values)
  sqrt(values)
}

# Works fine
cat("sqrt:", safe_sqrt(c(4, 9, 16)), "\n")

# Shows helpful error with caller context
tryCatch(
  safe_sqrt(c(4, -1, 16)),
  error = function(e) cat("Error:", conditionMessage(e), "\n")
)


    


      

      

    


    


  






Practice Exercise





  


    
# Exercise: Write a function trace_call() that, when called
# from anywhere, prints the full call chain from top to current.
# Example output:
#   Call chain: a(5) -> b(6) -> trace_call()

# Write your code below:



    


      

      

    


    


  







Click to reveal solution

```r


  

    
trace_call <- function() {
  n <- sys.nframe()
  calls <- character(n)
  for (i in 1:n) {
    calls[i] <- deparse(sys.call(i))
  }
  cat("Call chain:", paste(calls, collapse = " -> "), "\n")
}

a <- function(x) b(x + 1)
b <- function(y) c(y + 1)
c <- function(z) {
  trace_call()
  z
}

a(5)

    

      
      
    

    

  




**Explanation:** Walk through all stack frames from 1 to `sys.nframe()`, collecting each call expression with `sys.call(i)`. `deparse()` converts the call object to a readable string.





Summary







Function
Returns
Argument






sys.nframe()
Current stack depth
None




sys.call(n)
Call expression at frame n
Frame number (0 = current)




sys.frame(n)
Environment at frame n
Frame number (-1 = parent)




parent.frame()
Caller's environment
Equivalent to sys.frame(-1)




sys.function(n)
Function object at frame n
Frame number




match.call()
Current function's call
None (uses parent.frame internally)







FAQ



When would I use these in real code?



Most commonly for: (1) generating informative error messages that include the caller's context, (2) functions that need to evaluate expressions in the caller's environment (like subset() and with()), (3) debugging tools that walk the call stack.



What's the difference between sys.frame(-1) and parent.frame()?



They're identical. parent.frame(n) is sys.frame(-n). parent.frame() defaults to n=1, so parent.frame() = sys.frame(-1).



What's Next?



    


  1. R Namespaces — how package environments and the search path work together
    2. 


  2. R Environments — the foundational concept behind all stack frames
    3. 


  3. R Debugging — practical use of stack inspection for finding bugs
    4. 




        


        
      


      

        

        
© 2016- Selva Prabhakaran.
          This work is licensed under the Creative Commons License.