cli_progress_bar: cli progress bars
In RonMobile/cli: Helpers for Developing Command Line Interfaces

Description Usage Arguments Details Value See Also Examples

This is the reference manual of the three functions that create, update and terminate progress bars. For a tutorial see the cli progress bars.

cli_progress_bar() creates a progress bar.

cli_progress_update() updates the state of a progress bar, and potentially the display as well.

cli_progress_done() terminates a progress bar.

cli_progress_bar(
  name = NULL,
  status = NULL,
  type = c("iterator", "tasks", "download", "custom"),
  total = NA,
  format = NULL,
  format_done = NULL,
  format_failed = NULL,
  clear = getOption("cli.progress_clear", TRUE),
  current = TRUE,
  auto_terminate = type != "download",
  extra = NULL,
  .auto_close = TRUE,
  .envir = parent.frame()
)

cli_progress_update(
  inc = NULL,
  set = NULL,
  total = NULL,
  status = NULL,
  extra = NULL,
  id = NULL,
  force = FALSE,
  .envir = parent.frame()
)

cli_progress_done(id = NULL, .envir = parent.frame(), result = "done")

`name`	This is typically used as a label, and should be short, at most 20 characters.
`status`	New status string of the progress bar, if not `NULL`.
`type`	Type of the progress bar. It is used to select a default display if `format` is not specified. Currently supported types: `iterator`: e.g. a for loop or a mapping function, `tasks`: a (typically small) number of tasks, `download`: download of one file, `custom`: custom type, `format` must not be `NULL` for this type.
`total`	Total number of progress units, or `NA` if it is unknown. `cli_progress_update()` can update the total number of units. This is handy if you don't know the size of a download at the beginning, and also in some other casees. If `format` (plus `format_done` and `format_done`) will be updated if you change `total` from `NA` to a number, if you specify `NULL` for `format`. I.e. default format strings will be updated, custom ones won't be.
`format`	Format string. It has to be specified for custom progress bars, otherwise it is optional, and a default display is selected based on the progress bat type and whether the number of total units is known. Format strings may contain glue substitution, the support pluralization and cli styling.
`format_done`	Format string for successful termination. By default the same as `format`.
`format_failed`	Format string for unsuccessful termination. By default the same as `format`.
`clear`	Whether to remove the progress bar from the screen after it has temrinated.
`current`	Whether to use this progress bar as the current progress bar of the calling function. See more at 'The current progress bar' below.
`auto_terminate`	Whether to terminate the progress bar if the number of current units reaches the number of total units.
`extra`	Extra data to add to the progress bar. This can be used in custom format strings for example. It should be a named list. `cli_progress_update()` can update the extra data.
`.auto_close`	Whether to terminate the progress bar when the calling function (or the one with execution environment in `.envir` exits. (Auto termination does not work for progress bars created from the global environment, e.g. from a script.)
`.envir`	The environment to use for auto-termination and for glue substitution. It is also used to find and set the current progress bar.
`inc`	Increment in progress units. This is ignored if `set` is not `NULL`.
`set`	Set the current number of progress units to this value. Ignored if `NULL`.
`id`	Progress bar to update or terminate. If `NULL`, then the current progress bar of the calling function (or `.envir` if specified) is updated or terminated.
`force`	Whether to force a display update, even if no update is due.
`result`	String to select successful or unsuccessful termination. It is only used if the progress bar is not cleared from the screen. It can be one of `"done"`, `"failed"`, `"clear"`, and `"auto"`.

cli_progress_update() updates the state of the progress bar and potentially outputs the new progress bar to the display as well.

cli_progress_bar() returns the id of the new progress bar. The id is a string constant.

The current progress bar

If current = TRUE (the default), then the new progress bar will be the current progress bar of the calling frame. The previous current progress bar of the same frame, if there is any, is terminated.

cli_progress_update() returns the id of the progress bar, invisibly.

cli_progress_done() returns TRUE, invisibly, always.

cli_progress_message() and cli_progress_step() for simpler progress messages.

clean <- function() {
  cli_progress_bar("Cleaning data", total = 100)
  for (i in 1:100) {
    Sys.sleep(5/100)
    cli_progress_update()
  }
}
clean()