Open a logged step

log_step() is intended to be called from inside a function: it prints an opening line for msg and registers an automatic close that fires when the calling function's frame exits – whether by normal return, early return(), or an uncaught error propagating through it. Because the close is registered in the caller's frame rather than inside log_step() itself, nesting depth always stays in sync, even across errors. At top level, where there is no enclosing function frame to close on, use log_open() / log_close() instead.

Usage

log_step(
  msg,
  glyph = NULL,
  parent = NULL,
  group = NULL,
  close = FALSE,
  key = NULL
)

Arguments

msg

Character scalar. The step's label.

glyph

Optional character scalar overriding this step's glyph.

parent

Optional step handle (an id returned by log_open()/ log_step()) of a currently-open step to nest this one under. Defaults to the innermost open step. The target must still be open, else an error.

group

Optional named length-1 vector c(name = value). Adjacent log_step() calls sharing the same value are grouped under a single < name > header line. The value is the match key; the name is displayed.

close

Logical. When TRUE, the step is force-closed silently as soon as its opening line is printed: a header-only marker with no children and no Done line (and no automatic close is registered). Defaults to FALSE.

key

Optional character scalar giving this step a stable identity for re-run reconciliation. At top level (the global env) the label is used automatically, so re-running the same line re-anchors to that node instead of nesting under the previous run's leftovers. Pass key to override the automatic label key, or to keep two same-label steps that are open at once distinct. Ignored when parent is supplied.

Value

The step's internal id, invisibly.

Details

Opening a step at the same depth as an already-open step retires that earlier sibling automatically – its close line is printed with no explicit log_close() call. In the default nested pattern each log_step() descends one level deeper, so this same-level retirement applies when you place steps side by side via an explicit parent.

Examples

logtree_reset()
f <- function() {
  log_step("Doing work")
}
f()
#> ▶ Doing work
#> └─ ✔ Done  0.00s