R语言【cli】——cli_progress_bar()，cli_progress_update()，cli_progress_done()：创建、更新和终止进度条

最新推荐文章于 2024-06-03 09:54:18 发布

ALittleHigh

最新推荐文章于 2024-06-03 09:54:18 发布

阅读量869

点赞数 20

分类专栏： # cli 文章标签： r语言开发语言

本文链接：https://blog.csdn.net/whitedrogen/article/details/135673070

版权

cli 专栏收录该内容

27 篇文章 0 订阅

订阅专栏

Package cli version 3.6.0

Description

cli_progress_bar()：创建一个新的进度条。

cli_progress_update()：更新进度条状态和外观。

cli_progress_done()：终止进度条。

Usage

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")

Arguments

参数【name】：此参数可以看作是一个标签，内容应该简短，不超过20个字符。

参数【status】：表示进度条的新的状态字符串。

参数【type】：表示进度条的类型。当参数【format】未指定时，此参数将使用默认外观。目前支持的类型有：

iterator：一个 for 循环或一个 mapping 函数；
tasks：一组任务（通常数量较少）；
download：下载文件；
custom：自定义外观，如要使用此类型，则参数【format】不能为 NULL。

参数【total】：进度条单元的总体数量，当未知时应为 NA。cli_progress_update() 可以更新单元的总体数量。当你一开始并不知道下载的大小时，这是非常实用的。当参数【format】为 NULL，参数【format】（以及参数【format_done】和参数【format_failed】）会在参数【total】的值从 NA 改为一个数字时更新。即，默认格式字符串会更新，但是自定义的并不会。

参数【format】：格式化字符串。当使用自定义进度条时必须提供此项，否则可以选择不提供此项。进度条的外观类型将是默认的，单元的总体数量可知可不知。格式化字符串可以包含胶水语句，多元化和 cli 格式化。

参数【format_done】：成功终止的格式化字符串。默认与参数【format】一致。

参数【format_failed】：不成功终止的格式化字符串。默认与参数【format】一致。

参数【clear】：当进度条终止后，是否将它从屏幕上擦除。默认使用 cli.progress_clear()的选择，当未提供时选择 TRUE。

参数【current】：是否将此进度条视为当前调用函数的进度条。

参数【auto_terminate】：当目前的单元数量已经与总体单元数量一样时，是否立即终止进度条。

参数【extra】：向进度条增加额外的数据。这在使用自定义格式化字符串时很有用。您赢少使用一个命名列表。cli_progress_update() 可以更新额外数据。通常，您可以在格式字符串中引用局部变量，然后不需要使用此参数。在参数【extra】中显式地包含这些常量或变量可以使代码更简洁。在极少数情况下，当您需要从多个功能中引用相同的进度条时，您可以将它们添加到其他功能中。

参数【.auto_close】：是否在调用函数(或. environment中具有执行环境的函数)退出时终止进度条。(自动终止不适用于从全局环境中创建的进度条，例如从脚本中创建的进度条。)

参数【.envir】：用于自动终止和胶水替代的环境。它还用于查找和设置当前进度条。

参数【inc】：进度单位的增量。如果参数【set】不是NULL，则忽略此值。

参数【set】：将当前进度单位数设置为此值。如果为NULL则忽略。

参数【id】：更新或终止进度条。如果为NULL，则调用函数的当前进度条(如果指定了.envir)被更新或终止。

参数【force】：是否强制显示更新，即使没有更新。

参数【result】：选择成功或不成功终止的字符串。它仅在进度条未从屏幕上清除时使用。它可以是“done”、“failed”、“clear”和“auto”之一。

Examples

最好总是设置参数【name】，以使进度条提供更多信息。

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

进度条一共有3种内置外观

tasks <- function() {
  cli_progress_bar("Iterator", total = 3, type = "iterator", clear = FALSE)
  for (i in 1:3) {
    Sys.sleep(1)
    cli_progress_update()
  }
  cli_progress_done()
  
  cli_progress_bar("Tasks", total = 3, type = "tasks", clear = FALSE)
  for (i in 1:3) {
    Sys.sleep(1)
    cli_progress_update()
  }
  cli_progress_done()
  
  cli_progress_bar("Download", total = 3, type = "download", clear = FALSE)
  for (i in 1:3) {
    Sys.sleep(1)
    cli_progress_update()
  }
  cli_progress_done()
}

Iterator ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■  100% | ETA:  0s
⠹ 3/3 ETA:  0s | Tasks 
Download ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ | 0.0 kB/0.0 kB ETA:  0s

如果参数【total】未知，那么进度条的表现会有所不同。注意：您可以在 cli_progress_update() 中设置参数【total】，以防您在创建进度条后才知晓数量。

nototal <- function(){
  cli_progress_bar("Parameter tuning", clear = FALSE)
  for (i in 1:100){
    Sys.sleep(3/100)
    cli_progress_update()
  }
  cli_progress_done()
}

⠇ Parameter tuning 100 done (28/s) | 3.5s

初始化缓冲

更新屏幕上的进度条成本很高，所以cli 为了快速循环而尽量避免它。默认情况下，进度条只会在两秒后显示，或者在不到50%的迭代完成后显示一半。您可以使用 cli.progress_show_after 全局选项更改两秒的默认值。

在cli文档中，我们通常设置 cli.progress_show_after 为 0(零秒)，因此进度条立即显示。

fun <- function() {
  cli_alert("Starting now, at {Sys.time()}")
  cli_progress_bar(
    total = 100,
    format = "{cli::pb_bar} {pb_percent} @ {Sys.time()}",
    clear = FALSE
  )
  for (i in 1:100) {
    Sys.sleep(4/100)
    cli_progress_update()
  }
}
options(cli.progress_show_after = 2)
fun()

→ Starting now, at 2024-01-18 15:04:16
■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■  100% @ 2024-01-18 15:04:21

锁定当前进度条

默认情况下，cli将新的进度条设置为调用函数的当前进度条。当前进度条为cli进度条操作中的默认进度条。例如，如果cli_progress_update()中没有提供进度条id，则更新当前进度条。

每个函数只能有一个当前进度条，如果创建了一个新进度条，那么前一个进度条(如果有的话)将自动终止。当创建当前进度条的函数退出时，当前进度条也会终止。多亏了这些规则，大多数情况下你不需要显式地处理进度条id，也不需要显式地调用cli_progress_done():

fun <- function() {
  cli_progress_bar("First step ", total = 100, clear = FALSE)
  for (i in 1:100) {
    Sys.sleep(2/100)
    cli_progress_update()
  }
  cli_progress_bar("Second step", total = 100, clear = FALSE)
  for (i in 1:100) {
    Sys.sleep(2/100)
    cli_progress_update()
  }
}
fun()

First step  ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■  100% | ETA:  0s
Second step ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■  100% | ETA:  0s

在进度条运作时输出

Cli允许在进度条处于活动状态时发出常规的Cli输出(警报、标题、列表等)。在支持此功能的终端上，cli将暂时删除进度条，发出输出，然后恢复进度条。

fun <- function() {
  cli_alert_info("Before the progress bar")
  cli_progress_bar("Calculating", total = 100, clear=FALSE)
  for (i in 1:50) {
    Sys.sleep(4/100)
    cli_progress_update()
  }
  cli_alert_info("Already half way!")
  for (i in 1:50) {
    Sys.sleep(4/100)
    cli_progress_update()
  }
  cli_alert_info("All done")
}
fun()

ℹ Before the progress bar
ℹ Already half way!                                          
Calculating ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■  100% | ETA:  0s
ℹ All done

自定义格式化

除了内置类型之外，还可以指定自定义格式字符串。在这种情况下，进度变量可能有助于避免手动计算一些进度条数量，如ETA的经过时间。你也可以在调用函数中使用自己的变量:

fun <- function(urls) {
  cli_progress_bar(
    format = paste0(
      "{pb_spin} Downloading {.path {basename(url)}} ",
      "[{pb_current}/{pb_total}]   ETA:{pb_eta}"
    ),
    format_done = paste0(
      "{col_green(symbol$tick)} Downloaded {pb_total} files ",
      "in {pb_elapsed}."
    ),
    total = length(urls),
    clear = FALSE
  )
  for (url in urls) {
    cli_progress_update()
    Sys.sleep(5/10)
  }
}
fun(paste0("https://acme.com/data-", 1:10, ".zip"))