stacktrace

captureStackTraces(expr)

withLogErrors(expr, full = getOption("shiny.fullstacktrace", FALSE),
  offset = getOption("shiny.stacktraceoffset", TRUE))

printError(cond, full = getOption("shiny.fullstacktrace", FALSE),
  offset = getOption("shiny.stacktraceoffset", TRUE))

printStackTrace(cond, full = getOption("shiny.fullstacktrace", FALSE),
  offset = getOption("shiny.stacktraceoffset", TRUE))

extractStackTrace(calls, full = getOption("shiny.fullstacktrace", FALSE),
  offset = getOption("shiny.stacktraceoffset", TRUE))

formatStackTrace(calls, indent = "    ",
  full = getOption("shiny.fullstacktrace", FALSE),
  offset = getOption("shiny.stacktraceoffset", TRUE))

conditionStackTrace(cond)

conditionStackTrace(cond) <- value

..stacktraceon..(expr)

..stacktraceoff..(expr)

Arguments

expr	The expression to wrap.
full	If TRUE, then every element of sys.calls() will be included in the stack trace. By default (FALSE), calls that Shiny deems uninteresting will be hidden.
offset	If TRUE (the default), srcrefs will be reassigned from the calls they originated from, to the destinations of those calls. If you're used to stack traces from other languages, this feels more intuitive, as the definition of the function indicated in the call and the location specified by the srcref match up. If FALSE, srcrefs will be left alone (traditional R treatment where the srcref is of the callsite).
cond	An condition object (generally, an error).
indent	A string to prefix every line of the stack trace.
value	The stack trace value to assign to the condition.
cond	A condition that may have previously been annotated by captureStackTraces (or withLogErrors).

Value

printError and printStackTrace return invisible(). The other functions pass through the results of expr.

Description

Advanced (borderline internal) functions for capturing, printing, and manipulating stack traces.

Details

captureStackTraces runs the given expr and if any uncaught errors occur, annotates them with stack trace info for use by printError and printStackTrace. It is not necessary to use captureStackTraces around the same expression as withLogErrors, as the latter includes a call to the former. Note that if expr contains calls (either directly or indirectly) to try, or tryCatch with an error handler, stack traces therein cannot be captured unless another captureStackTraces call is inserted in the interior of the try or tryCatch. This is because these calls catch the error and prevent it from traveling up to the condition handler installed by captureStackTraces.

withLogErrors captures stack traces and logs errors that occur in expr, but does allow errors to propagate beyond this point (i.e. it doesn't catch the error). The same caveats that apply to captureStackTraces with regard to try/tryCatch apply to withLogErrors.

printError prints the error and stack trace (if any) using warning(immediate.=TRUE). printStackTrace prints the stack trace only.

extractStackTrace takes a list of calls (e.g. as returned from conditionStackTrace(cond)) and returns a data frame with one row for each stack frame and the columns num (stack frame number), call (a function name or similar), and loc (source file path and line number, if available).

formatStackTrace is similar to extractStackTrace, but it returns a preformatted character vector instead of a data frame.

conditionStackTrace and conditionStackTrace<- are accessor functions for getting/setting stack traces on conditions.

The two functions ..stacktraceon.. and ..stacktraceoff.. have no runtime behavior during normal execution; they exist only to create artifacts on the stack trace (sys.call()) that instruct the stack trace pretty printer what parts of the stack trace are interesting or not. The initial state is 1 and we walk from the outermost call inwards. Each ..stacktraceoff.. decrements the state by one, and each ..stacktraceon.. increments the state by one. Any stack trace frame whose value is less than 1 is hidden, and finally, the ..stacktraceon.. and ..stacktraceoff.. calls themselves are hidden too.

Examples

# Keeps tryCatch and withVisible related calls off the
# pretty-printed stack trace

visibleFunction1 <- function() {
  stop("Kaboom!")
}

visibleFunction2 <- function() {
  visibleFunction1()
}

hiddenFunction <- function(expr) {
  expr
}

# An example without ..stacktraceon/off.. manipulation.
# The outer "try" is just to prevent example() from stopping.
try({
  # The withLogErrors call ensures that stack traces are captured
  # and that errors that bubble up are logged using warning().
  withLogErrors({
    # tryCatch and withVisible are just here to add some noise to
    # the stack trace.
    tryCatch(
      withVisible({
        hiddenFunction(visibleFunction2())
      })
    )
  })
})
Warning message:
Error in visibleFunction1: Kaboom!
Stack trace (innermost first):
    33: visibleFunction1 [<text>#5]
    32: visibleFunction2 [<text>#9]
    31: hiddenFunction [<text>#13]
    30: withVisible [<text>#26]
    29: tryCatchList
    28: tryCatch
    27: withCallingHandlers [<text>#24]
    26: captureStackTraces [/Users/winston/Dropbox/Projects/shiny/R/conditions.R#108]
    25: withCallingHandlers
    24: withLogErrors [/Users/winston/Dropbox/Projects/shiny/R/conditions.R#130]
    23: doTryCatch [<text>#21]
    22: tryCatchOne
    21: tryCatchList
    20: tryCatch
    19: try
    18: eval
    17: eval
    16: withVisible
    15: withCallingHandlers
    14: doTryCatch
    13: tryCatchOne
    12: tryCatchList
    11: tryCatch
    10: try
     9: handle
     8: timing_fn
     7: evaluate_call
     6: evaluate
     5: to_html.examples
     4: to_html
     3: to_html.Rd_doc
     2: build_topics
     1: build_site

# Now the same example, but with ..stacktraceon/off.. to hide some
# of the less-interesting bits (tryCatch and withVisible).
..stacktraceoff..({
  try({
    withLogErrors({
      tryCatch(
        withVisible(
          hiddenFunction(
            ..stacktraceon..(visibleFunction2())
          )
        )
      )
    })
  })
})
Warning message:
Error in visibleFunction1: Kaboom!
Stack trace (innermost first):
    35: visibleFunction1 [<text>#5]
    34: visibleFunction2 [<text>#9]
    18: eval
    17: eval
    16: withVisible
    15: withCallingHandlers
    14: doTryCatch
    13: tryCatchOne
    12: tryCatchList
    11: tryCatch
    10: try
     9: handle
     8: timing_fn
     7: evaluate_call
     6: evaluate
     5: to_html.examples
     4: to_html
     3: to_html.Rd_doc
     2: build_topics
     1: build_site