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"))
✔ Downloaded 10 files in 4.8s.