R: Simplified cli progress messages, with styling

cli_progress_step {cli}

R Documentation

Simplified cli progress messages, with styling

Description

This is a simplified progress bar, a single (dynamic) message, without progress units.

Usage

cli_progress_step(
  msg,
  msg_done = msg,
  msg_failed = msg,
  spinner = FALSE,
  class = if (!spinner) ".alert-info",
  current = TRUE,
  .auto_close = TRUE,
  .envir = parent.frame(),
  ...
)

Arguments

`msg`	Message to show. It may contain glue substitution and cli styling. It can be updated via `cli_progress_update()`, as usual. It is style as a cli info alert (see `cli_alert_info()`).
`msg_done`	Message to show on successful termination. By default this it is the same as `msg` and it is styled as a cli success alert (see `cli_alert_success()`).
`msg_failed`	Message to show on unsuccessful termination. By default it is the same as `msg` and it is styled as a cli danger alert (see `cli_alert_danger()`).
`spinner`	Whether to show a spinner at the beginning of the line. To make the spinner spin, you'll need to call `cli_progress_update()` regularly.
`class`	cli class to add to the message. By default there is no class for steps with a spinner.
`current`	Passed to `cli_progress_bar()`.
`.auto_close`	Passed to `cli_progress_bar()`.
`.envir`	Passed to `cli_progress_bar()`.
`...`	Passed to `cli_progress_bar()`.

Details

cli_progress_step() always shows the progress message, even if no update is due.

Basic use

f <- function() {
  cli_progress_step("Downloading data")
  Sys.sleep(2)
  cli_progress_step("Importing data")
  Sys.sleep(1)
  cli_progress_step("Cleaning data")
  Sys.sleep(2)
  cli_progress_step("Fitting model")
  Sys.sleep(3)
}
f()

Spinner

You can add a spinner to some or all steps with spinner = TRUE, but note that this will only work if you call cli_progress_update() regularly.

f <- function() {
  cli_progress_step("Downloading data", spinner = TRUE)
  for (i in 1:100) { Sys.sleep(2/100); cli_progress_update() }
  cli_progress_step("Importing data")
  Sys.sleep(1)
  cli_progress_step("Cleaning data")
  Sys.sleep(2)
  cli_progress_step("Fitting model", spinner = TRUE)
  for (i in 1:100) { Sys.sleep(3/100); cli_progress_update() }
}
f()

Dynamic messages

You can make the step messages dynamic, using glue templates. Since cli_progress_step() show that message immediately, we need to initialize msg first.

f <- function() {
  msg <- ""
  cli_progress_step("Downloading data{msg}", spinner = TRUE)
  for (i in 1:100) {
    Sys.sleep(2/100)
    msg <- glue::glue(", got file {i}/100")
    cli_progress_update()
  }
  cli_progress_step("Importing data")
  Sys.sleep(1)
  cli_progress_step("Cleaning data")
  Sys.sleep(2)
  cli_progress_step("Fitting model", spinner = TRUE)
  for (i in 1:100) { Sys.sleep(3/100); cli_progress_update() }
}
f()

Termination messages

You can specify a different message for successful and/or unsuccessful termination:

f <- function() {
  size <- 0L
  cli_progress_step(
    "Downloading data.",
    msg_done = "Downloaded {prettyunits::pretty_bytes(size)}.",
    spinner = TRUE
  )
  for (i in 1:100) {
    Sys.sleep(3/100)
    size <- size + 8192
    cli_progress_update()
  }
}
f()