Skip to contents

Run an expression with top-level error handling and a run summary

Source: R/run.R
with_logging.Rd

Wrap a script or pipeline's top-level call in with_logging() so an uncaught error leaves a clean, correctly-colored tree instead of dimmed "interrupted" steps. On error, every currently open step is marked failed, the error is logged as a leaf line, then rethrown – with_logging() never silently swallows errors. It also prints a "Run complete" / "Run failed" summary line with elapsed time.

Usage

with_logging(expr, summary = TRUE, global = FALSE)

Arguments

expr

Code to run. Omitted when global = TRUE.

summary

Print an end-of-run summary line? Default TRUE. In global mode only the "Run failed" line is printed (on an uncaught error); there is no frame exit to hang a "Run complete" line on.

global

If TRUE, do not wrap an expression; instead install a session-persistent global error handler for use at the top level of a script. On an error that reaches top level unhandled while logtree steps are open, it marks those steps failed and logs the error message as a leaf – the same result as the block form, but without wrapping the body. It fires only for genuinely uncaught top-level errors (an inner tryCatch() that catches first pre-empts it) and only when steps are open. The handler persists until logtree_reset(). Must be called from a clean top level – the first line of a script: calling it where condition handlers are active (inside tryCatch(), or a function running under one) errors, by design. Requires R (>= 4.0).

Value

In block mode, the value of expr, invisibly. In global mode, NULL, invisibly.

Details

Note: expr is lazily evaluated, so log_step() calls written inside the { ... } block close when the function lexically enclosing that block returns – not necessarily when with_logging() itself returns. Use with_logging({ ... }) as a function's entire body to keep these in sync; if other code runs after the call in the same function, steps opened inside the block stay open until that function returns.

The global = TRUE form is meant for the top level of a script, where there is no frame to wrap. It is not shown in the examples below because it installs a session-persistent handler and is only meaningful for an error that reaches top level:

with_logging(global = TRUE)
log_open("Load data")
stop("EOF")   # marks the open step failed + logs "EOF" before R exits

Examples

logtree_reset()
with_logging({
  log_step("Step one")
  log_success("done")
})
#> ▶ Step one
#> ├─ ✔ done
#> ✔ Run complete in 0.00s
#> └─ ◌ Done  0.00s