Indicate the start and termination of some computation in the status bar (superseded)

The cli_process_*() functions are superseded by the cli_progress_message() and cli_progress_step() functions, because they have a better default behavior.

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

This function supports inline markup.

The cli_progress_message() and cli_progress_step() functions, for a superior API.

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

Other functions supporting inline markup: cli_abort(), cli_alert(), cli_blockquote(), cli_bullets(), cli_bullets_raw(), cli_dl(), cli_h1(), cli_li(), cli_ol(), cli_progress_along(), cli_progress_bar(), cli_progress_message(), cli_progress_output(), cli_progress_step(), cli_rule, cli_status(), cli_status_update(), cli_text(), cli_ul(), format_error(), format_inline()

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 ... failed
#> 
#> <simpleError in fun(): Failed>

## 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 ... done
#>