Update the status bar (superseded)

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

The status bar is the last line of the terminal. cli apps can use this to show status information, progress bars, etc. The status bar is kept intact by all semantic cli output.

Usage

cli_status(
  msg,
  msg_done = paste(msg, "... done"),
  msg_failed = paste(msg, "... failed"),
  .keep = FALSE,
  .auto_close = TRUE,
  .envir = parent.frame(),
  .auto_result = c("clear", "done", "failed", "auto")
)

Arguments

msg

The text to show, a character vector. It will be collapsed into a single string, and the first line is kept and cut to console_width(). The message is often associated with the start of a calculation.

msg_done

The message to use when the message is cleared, when the calculation finishes successfully. If .auto_close is TRUE and .auto_result is "done", then this is printed automatically when the calling function (or .envir) finishes.

msg_failed

The message to use when the message is cleared, when the calculation finishes unsuccessfully. If .auto_close is TRUE and .auto_result is "failed", then this is printed automatically when the calling function (or .envir) finishes.

.keep

What to do when this status bar is cleared. If TRUE then the content of this status bar is kept, as regular cli output (the screen is scrolled up if needed). If FALSE, then this status bar is deleted.

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

.auto_result

What to do when auto-closing the status bar.

Value

The id of the new status bar container element, invisibly.

Details

Use cli_status_clear() to clear the status bar.

Often status messages are associated with processes. E.g. the app starts downloading a large file, so it sets the status bar accordingly. Once the download is done (or has failed), the app typically updates the status bar again. cli automates much of this, via the msg_done, msg_failed, and .auto_result arguments. See examples below.

See also

Status bars support inline markup.

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

Other status bar: cli_process_start(), 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_process_start(), cli_progress_along(), cli_progress_bar(), cli_progress_message(), cli_progress_output(), cli_progress_step(), cli_rule, cli_status_update(), cli_text(), cli_ul(), format_error(), format_inline()