cli_progress_along: Add a progress bar to a mapping function or for loop

View source: R/progress-along.R

cli_progress_alongR Documentation

Add a progress bar to a mapping function or for loop

Description

Note that this function is currently experimental!

Use cli_progress_along() in a mapping function or in a for loop, to add a progress bar. It uses cli_progress_bar() internally.

Usage

cli_progress_along(
  x,
  name = NULL,
  total = length(x),
  ...,
  .envir = parent.frame()
)

Arguments

x

Sequence to add the progress bar to.

name

Name of the progress bar, a label, passed to cli_progress_bar().

total

Passed to cli_progress_bar().

...

Passed to cli_progress_bar().

.envir

Passed to cli_progress_bar().

Details

for loop

A for loop with cli_progress_along() looks like this:

for (i in cli_progress_along(seq)) {
  ...
}

A complete example:

clifun <- function() {
  for (i in cli_progress_along(1:100, "Downloading")) {
     Sys.sleep(4/100)
  }
}
clifun()

progress-along-1.svg

lapply() and other mapping functions

They will look like this:

lapply(cli_progress_along(X), function(i) ...)

A complete example:

res <- lapply(cli_progress_along(1:100, "Downloading"), function(i) {
  Sys.sleep(4/100)
})

progress-along-2.svg

Custom format string

clifun <- function() {
  for (i in cli_progress_along(1:100,
      format = "Downloading data file {cli::pb_current}")) {
     Sys.sleep(4/100)
  }
}
clifun()

progress-along-3.svg

Breaking out of loops

Note that if you use break in the for loop, you probably want to terminate the progress bar explicitly when breaking out of the loop, or right after the loop:

for (i in cli_progress_along(seq)) {
  ...
  if (cond) cli_progress_done() && break
  ...
}

Value

An index vector from 1 to length(x) that triggers progress updates as you iterate over it.

See Also

This function supports inline markup.

cli_progress_bar() and the traditional progress bar API.

Other progress bar functions: cli_progress_bar(), cli_progress_builtin_handlers(), cli_progress_message(), cli_progress_num(), cli_progress_output(), cli_progress_step(), cli_progress_styles(), progress-variables

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_process_start(), 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()


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