Open a step under manual lifetime control

Like log_step() but with no automatic close: the step stays open until you close it yourself with log_close(). This is what you want at top level (a script or the REPL), where there is no enclosing function frame for log_step() to hang its close on. You may also attach the step to a chosen open parent rather than the innermost open step, letting you build the tree by hand.

Usage

log_open(
  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), as in log_step().
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. Defaults to FALSE.
key: Optional character scalar giving this step a stable identity for re-run reconciliation, as in log_step(). At top level the label is used automatically, so re-running the same log_open() line re-anchors to that node instead of nesting under the previous run's leftovers. Ignored when parent is supplied.

Value

The step's id, invisibly. Capture it to pass to log_close() or as another step's parent.

Details

Opening a step at the same depth as an already-open step – for example by linking to a shared parent – first closes that sibling and its descendants, since a new sibling means the previous subtree is done.

Examples

logtree_reset()
s1 <- log_open("Step 1")
#> ▶ Step 1
log_info("a child line")
#> ├─ ℹ a child line
log_close(s1)
#> └─ ✔ Done  0.00s