Indicate the start and termination of some computation in the status bar

Typically you call cli_process_start() to start the process, and then cli_process_done() when it is done. If an error happens before cli_process_done() is called, then cli automatically shows the message for unsuccessful termination.

cli_process_start(
  msg,
  msg_done = paste(msg, "... done"),
  msg_failed = paste(msg, "... failed"),
  on_exit = c("auto", "failed", "done"),
  msg_class = "alert-info",
  done_class = "alert-success",
  failed_class = "alert-danger",
  .auto_close = TRUE,
  .envir = parent.frame()
)

cli_process_done(
  id = NULL,
  msg_done = NULL,
  .envir = parent.frame(),
  done_class = "alert-success"
)

cli_process_failed(
  id = NULL,
  msg = NULL,
  msg_failed = NULL,
  .envir = parent.frame(),
  failed_class = "alert-danger"
)

Arguments

msg	The message to show to indicate the start of the process or computation. It will be collapsed into a single string, and the first line is kept and cut to console_width().
msg_done	The message to use for successful termination.
msg_failed	The message to use for unsuccessful termination.
on_exit	Whether this process should fail or terminate successfully when the calling function (or the environment in .envir) exits.
msg_class	The style class to add to the message. Use an empty string to suppress styling.
done_class	The style class to add to the successful termination message. Use an empty string to suppress styling.a
failed_class	The style class to add to the unsuccessful termination message. Use an empty string to suppress styling.a
.auto_close	Whether to clear the status bar when the calling function finishes (or ‘.envir’ is removed from the stack, if specified).
.envir	Environment to evaluate the glue expressions in. It is also used to auto-clear the status bar if .auto_close is TRUE.
id	Id of the status bar container to clear. If id is not the id of the current status bar (because it was overwritten by another status bar container), then the status bar is not cleared. If NULL (the default) then the status bar is always cleared.

Value

Id of the status bar container.

Details

If you handle the errors of the process or computation, then you can do the opposite: call cli_process_start() with on_exit = "done", and in the error handler call cli_process_failed(). cli will automatically call cli_process_done() on successful termination, when the calling function finishes.

See examples below.

See also

Other status bar: cli_status_clear(), cli_status_update(), cli_status()

Examples

## Failure by default
fun <- function() {
  cli_process_start("Calculating")
  if (interactive()) Sys.sleep(1)
  if (runif(1) < 0.5) stop("Failed")
  cli_process_done()
}
tryCatch(fun(), error = function(err) err)
#> ℹ Calculating
#> ✔ Calculating ... done
#> 

## Success by default
fun2 <- function() {
  cli_process_start("Calculating", on_exit = "done")
  tryCatch({
    if (interactive()) Sys.sleep(1)
    if (runif(1) < 0.5) stop("Failed")
  }, error = function(err) cli_process_failed())
}
fun2()
#> ℹ Calculating
#> ✖ Calculating ... failed
#>