cli_process_start: Indicate the start and termination of some computation in the...

In cli: Helpers for Developing Command Line Interfaces

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

Description

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.

Usage

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.

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.

Value

Id of the status bar container.

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_clear(), cli_status_update(), cli_status()

Other functions supporting inline markup: cli_abort(), cli_alert(), cli_blockquote(), cli_bullets_raw(), cli_bullets(), 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_update(), cli_status(), 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)

## 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()

cli documentation built on June 22, 2024, 10:57 a.m.