A backtrace captures the sequence of calls that lead to the current
function, sometimes called the call stack. Because of lazy
evaluation, the call stack in R is actually a tree, which the
summary() method of this object will reveal.
trace_back(top = NULL, bottom = NULL) trace_length(trace)
| top | The first frame environment to be included in the backtrace. This becomes the top of the backtrace tree and represents the oldest call in the backtrace. This is needed in particular when you call |
|---|---|
| bottom | The last frame environment to be included in the backtrace. This becomes the rightmost leaf of the backtrace tree and represents the youngest call in the backtrace. Set this when you would like to capture a backtrace without the capture context. Can also be an integer that will be passed to |
| trace | A backtrace created by |
trace_length() returns the number of frames in a backtrace.
# Trim backtraces automatically (this improves the generated # documentation for the rlang website and the same trick can be # useful within knitr documents): options(rlang_trace_top_env = current_env()) f <- function() g() g <- function() h() h <- function() trace_back() # When no lazy evaluation is involved the backtrace is linear # (i.e. every call has only one child) f() #> █ #> 1. └─f() #> 2. └─g() #> 3. └─h() # Lazy evaluation introduces a tree like structure identity(identity(f())) #> █ #> 1. ├─base::identity(identity(f())) #> 2. ├─base::identity(f()) #> 3. └─f() #> 4. └─g() #> 5. └─h() identity(try(f())) #> █ #> 1. ├─base::identity(try(f())) #> 2. ├─base::try(f()) #> 3. │ └─base::tryCatch(...) #> 4. │ └─base:::tryCatchList(expr, classes, parentenv, handlers) #> 5. │ └─base:::tryCatchOne(expr, names, parentenv, handlers[[1L]]) #> 6. │ └─base:::doTryCatch(return(expr), name, parentenv, handler) #> 7. └─f() #> 8. └─g() #> 9. └─h() try(identity(f())) #> █ #> 1. ├─base::try(identity(f())) #> 2. │ └─base::tryCatch(...) #> 3. │ └─base:::tryCatchList(expr, classes, parentenv, handlers) #> 4. │ └─base:::tryCatchOne(expr, names, parentenv, handlers[[1L]]) #> 5. │ └─base:::doTryCatch(return(expr), name, parentenv, handler) #> 6. ├─base::identity(f()) #> 7. └─f() #> 8. └─g() #> 9. └─h() # When printing, you can request to simplify this tree to only show # the direct sequence of calls that lead to `trace_back()` x <- try(identity(f())) x #> █ #> 1. ├─base::try(identity(f())) #> 2. │ └─base::tryCatch(...) #> 3. │ └─base:::tryCatchList(expr, classes, parentenv, handlers) #> 4. │ └─base:::tryCatchOne(expr, names, parentenv, handlers[[1L]]) #> 5. │ └─base:::doTryCatch(return(expr), name, parentenv, handler) #> 6. ├─base::identity(f()) #> 7. └─f() #> 8. └─g() #> 9. └─h() print(x, simplify = "branch") #> 1. base::try(identity(f())) #> 7. f() #> 8. g() #> 9. h() # With a little cunning you can also use it to capture the # tree from within a base NSE function x <- NULL with(mtcars, {x <<- f(); 10}) #> [1] 10 x #> █ #> 1. ├─base::with(...) #> 2. └─base::with.default(...) #> 3. └─base::eval(substitute(expr), data, enclos = parent.frame()) #> 4. └─base::eval(substitute(expr), data, enclos = parent.frame()) #> 5. └─f() #> 6. └─g() #> 7. └─h() # Restore default top env for next example options(rlang_trace_top_env = NULL) # When code is executed indirectly, i.e. via source or within an # RMarkdown document, you'll tend to get a lot of guff at the beginning # related to the execution environment: conn <- textConnection("summary(f())") source(conn, echo = TRUE, local = TRUE) #> #> > summary(f()) #> █ #> 1. ├─base::tryCatch(...) #> 2. │ └─base:::tryCatchList(expr, classes, parentenv, handlers) #> 3. │ ├─base:::tryCatchOne(...) #> 4. │ │ └─base:::doTryCatch(return(expr), name, parentenv, handler) #> 5. │ └─base:::tryCatchList(expr, names[-nh], parentenv, handlers[-nh]) #> 6. │ └─base:::tryCatchOne(expr, names, parentenv, handlers[[1L]]) #> 7. │ └─base:::doTryCatch(return(expr), name, parentenv, handler) #> 8. ├─base::withCallingHandlers(...) #> 9. ├─base::saveRDS(...) #> 10. ├─base::do.call(...) #> 11. ├─(function (what, args, quote = FALSE, envir = parent.frame()) ... #> 12. └─(function (..., crayon_enabled, crayon_colors, pkgdown_internet) ... #> 13. └─pkgdown::build_site(...) #> 14. └─pkgdown:::build_site_local(...) #> 15. └─pkgdown::build_reference(...) #> 16. └─purrr::map(...) #> 17. └─pkgdown:::.f(.x[[i]], ...) #> 18. ├─base::withCallingHandlers(...) #> 19. └─pkgdown:::data_reference_topic(...) #> 20. └─pkgdown:::run_examples(...) #> 21. └─pkgdown:::highlight_examples(code, topic, env = env) #> 22. └─downlit::evaluate_and_highlight(...) #> 23. └─evaluate::evaluate(code, child_env(env), new_device = TRUE, output_handler = output_handler) #> 24. └─evaluate:::evaluate_call(...) #> 25. ├─evaluate:::timing_fn(...) #> 26. ├─evaluate:::handle(...) #> 27. │ └─base::try(f, silent = TRUE) #> 28. │ └─base::tryCatch(...) #> 29. │ └─base:::tryCatchList(expr, classes, parentenv, handlers) #> 30. │ └─base:::tryCatchOne(expr, names, parentenv, handlers[[1L]]) #> 31. │ └─base:::doTryCatch(return(expr), name, parentenv, handler) #> 32. ├─base::withCallingHandlers(...) #> 33. ├─base::withVisible(eval(expr, envir, enclos)) #> 34. └─base::eval(expr, envir, enclos) #> 35. └─base::eval(expr, envir, enclos) #> 36. ├─base::source(conn, echo = TRUE, local = TRUE) #> 37. │ ├─base::withVisible(eval(ei, envir)) #> 38. │ └─base::eval(ei, envir) #> 39. │ └─base::eval(ei, envir) #> 40. ├─base::summary(f()) #> 41. └─f() #> 42. └─g() #> 43. └─h() close(conn) # To automatically strip this off, specify which frame should be # the top of the backtrace. This will automatically trim off calls # prior to that frame: top <- current_env() h <- function() trace_back(top) conn <- textConnection("summary(f())") source(conn, echo = TRUE, local = TRUE) #> #> > summary(f()) #> █ #> 1. ├─base::summary(f()) #> 2. └─f() #> 3. └─g() #> 4. └─h() close(conn)