ml-progress

终端/控制台的进度指示器。

• 单行
• 不使用ANSI转义码，仅使用 \r
• 后台线程进行及时更新
• 有观点的语法

早期版本 - 这尚未得到适当测试。

用法

1. 或者
   • 使用 Progress 结构体和 progress! 宏创建（如果您不需要自定义配置），或者
   • 使用 ProgressBuilder 结构体和 progress_builder! 宏创建，设置自定义选项，然后使用 build 方法创建 Progress。
2. 在处理过程中，使用 inc 和 message 方法更新状态。
3. 使用以下方法之一完成： finish、finish_and_clear 或 finish_at_current_pos。

示例

默认项

use ml_progress::progress;

let progress = progress!(10)?;
for _ in 0..10 {
    // std::thread::sleep(std::time::Duration::from_millis(500));
    progress.inc(1);
}
progress.finish();

# Ok::<(), ml_progress::Error>(())

##############################-------------------- 6/10 (2s)

自定义项

use ml_progress::progress;

let progress = progress!(
    10;
    "[" percent "] " pos "/" total " " bar_fill " (" eta_hms ")"
)?;
for _ in 0..10 {
    // std::thread::sleep(std::time::Duration::from_millis(500));
    progress.inc(1);
}
progress.finish();

# Ok::<(), ml_progress::Error>(())

[ 60%] 6/10 ########################----------------- (0:02)

自定义配置

use ml_progress::progress_builder;

let progress = progress_builder!(
    "[" percent "] " pos_group "/" total_group " " bar_fill " (" eta_hms ")"
)
.total(Some(10000))
.thousands_separator(",")
.build()?;

for _ in 0..10 {
    // std::thread::sleep(std::time::Duration::from_millis(500));
    progress.inc(1000);
}
progress.finish();

# Ok::<(), ml_progress::Error>(())

[ 60%] 6,000/10,000 ###################-------------- (0:02)

项

项与 progress! 和 progress_builder! 宏一起使用。

• 每个项都是一个单个标记（例如 bar_fill）或括号内的多个标记（例如 (eta "{:2}{:1}")）。
• 项之间没有分隔符，除了空格。
• 最多允许一个 *_fill 项。

摘要

所有可能项的摘要。有关更多详细信息，请参阅下面。

"foo"                   // "foo"

bar_fill                // "######----"

eta                     // "5m"         ; same as (eta "{}{}")
(eta FORMAT NONE)       // u64, &str

eta_hms                 // "5:23"

message_fill            // "foo"

percent                 // " 23%"       ; same as (percent "{:3.0}%")
(percent FORMAT NONE)   // f64

pos                     // "1234567"    ; same as (pos     "{}"     )
pos_group               // "1 234 567"  ; same as (pos     "{:#}"   )
pos_bin                 // "1.18 Mi"    ; same as (pos_bin "{:#} {}")
pos_dec                 // "1.23 M"     ; same as (pos_dec "{:#} {}")
(pos     FORMAT)        // u64
(pos_bin FORMAT)        // f64, prefix
(pos_dec FORMAT)        // f64, prefix

speed                   // "1234567"    ; same as (speed     "{:#}"   )
speed_int               // "1234567"    ; same as (speed_int "{}"     )
speed_group             // "1 234 567"  ; same as (speed_int "{:#}"   )
speed_bin               // "1.18 Mi"    ; same as (speed_bin "{:#} {}")
speed_dec               // "1.23 M"     ; same as (speed_dec "{:#} {}")
(speed     FORMAT NONE) // f64
(speed_int FORMAT NONE) // u64
(speed_bin FORMAT NONE) // f64, prefix
(speed_dec FORMAT NONE) // f64, prefix

total                   // "1234567"    ; same as (total     "{}"     )
total_group             // "1 234 567"  ; same as (total     "{:#}"   )
total_bin               // "1.18 Mi"    ; same as (total_bin "{:#} {}")
total_dec               // "1.23 M"     ; same as (total_dec "{:#} {}")
(total     FORMAT NONE) // u64
(total_bin FORMAT NONE) // f64, prefix
(total_dec FORMAT NONE) // f64, prefix

(|state| EXPR)

格式

• 普通的Rust格式字符串，对特殊处理标志 # "alternate" 进行处理（见下文）。

无

• 当问题的值是 None 时，显示的文本值。
  • 有关值何时为 None，请参阅 State 的相应函数。
• 这是可选的，可以省略。默认值是空字符串。

前缀

• 以 _bin 结尾的项使用基于1024的二元前缀（Ki、Mi、Gi、...）。
• 以 _dec 结尾的项使用基于1000的十进制前缀（k、M、G、...）。

如果值低于1024或1000，则前缀为空字符串。

交替格式

当在 FORMAT 中使用 # "alternate" 标志时，根据类型应用以下规则

• u64 以每三位数字为一组进行格式化。
  • 可以使用 ProgressBuilder::thousands_separator 设置千位分隔符，默认为空格。
  • 例如，使用 1234567 和 "{:#}" 时，将显示为 "1 234 567"（默认分隔符）。
• f64
  • 格式 精度（默认：4）被视为 "适合宽度"，值将显示最大小数位数，以适应此宽度，如果无法适应，则不带小数。
  • 使用 pos_bin、pos_dec、total_bin 和 total_dec：具有空前缀的金额将不带小数显示。
  • 示例
    • 使用 1.2345 和 "{:#}" 时，显示为 "1.23"
    • 使用 12.345 和 "{:#}" 时，显示为 "12.3"
    • 使用 123.45 和 "{:#}" 时，显示为 "123"
    • 使用 1234.5 和 "{:#}" 时，显示为 "1235"
    • 使用 12345 和 "{:#}" 时，显示为 "12345"
• 前缀
  • "{:#}" 以原样显示空前缀，并带空格显示其他前缀。

文本

"foo"                   // "foo"

显示给定的文本字符串。

bar_fill

bar_fill                // "######----"

显示进度条，填充行上的剩余空间。

• 如果 total 是 None，则显示空格。

eta

eta                     // "5m"         ; same as (eta "{}{}")
(eta FORMAT)            // u64, &str
(eta FORMAT NONE)

以近似格式显示剩余时间估计：数量和单位，或者不可用时显示 NONE。

• 数量是完整单位数，即它不是四舍五入的。
• 单位可以是 h（小时）、m（分钟）或 s（秒）

eta_hms

eta_hms                 // "12:34:56"   "0:56"

以小时/分钟/秒显示剩余时间估计，如果不可用时则显示空字符串。

• 根据大小，格式可以是 H:MM:SS、MM:SS 或 M:SS。
• 值是完整秒数，即它不是四舍五入的。

message_fill

message_fill            // "foo"

显示使用 Progress::message 设置的消息，填充行上的剩余空间。

percent

percent                 // " 23%"       ; same as (percent "{:3.0}%")
(percent FORMAT)        // f64
(percent FORMAT NONE)

显示完成百分比或如果 total 是 None，则显示 NONE。

pos

pos                     // "1234567"    ; same as (pos     "{}"     )
pos_group               // "1 234 567"  ; same as (pos     "{:#}"   )
pos_bin                 // "1.18 Mi"    ; same as (pos_bin "{:#} {}")
pos_dec                 // "1.23 M"     ; same as (pos_dec "{:#} {}")

(pos     FORMAT)        // u64
(pos_bin FORMAT)        // f64, prefix
(pos_dec FORMAT)        // f64, prefix

显示位置。

• pos - 作为整数
• pos_group - 作为整数，以三位一组数字
• pos_bin - 作为带有二进制前缀的浮点数
• pos_dec - 作为带有十进制前缀的浮点数

speed

speed                   // "1234567"    ; same as (speed     "{:#}"   )
speed_int               // "1234567"    ; same as (speed_int "{}"     )
speed_group             // "1 234 567"  ; same as (speed_int "{:#}"   )
speed_bin               // "1.18 Mi"    ; same as (speed_bin "{:#} {}")
speed_dec               // "1.23 M"     ; same as (speed_dec "{:#} {}")
(speed     FORMAT)      // f64
(speed     FORMAT NONE)
(speed_int FORMAT)      // u64
(speed_int FORMAT NONE)
(speed_bin FORMAT)      // f64, prefix
(speed_bin FORMAT NONE)
(speed_dec FORMAT)      // f64, prefix
(speed_dec FORMAT NONE)

以每秒步数显示速度或如果速度不可用，则显示 NONE。

• speed - 作为浮点数
• speed_int - 作为整数
• speed_group - 作为整数，以三位一组数字
• speed_bin - 作为带有二进制前缀的浮点数
• speed_dec - 作为带有十进制前缀的浮点数

total

total                   // "1234567"    ; same as (total     "{}"     )
total_group             // "1 234 567"  ; same as (total     "{:#}"   )
total_bin               // "1.18 Mi"    ; same as (total_bin "{:#} {}")
total_dec               // "1.23 M"     ; same as (total_dec "{:#} {}")

(total     FORMAT)      // u64
(total     FORMAT NONE)
(total_bin FORMAT)      // f64, prefix
(total_bin FORMAT NONE)
(total_dec FORMAT)      // f64, prefix
(total_dec FORMAT NONE)

显示总数或如果 total 是 None，则显示 NONE。

• total - 作为整数
• total_group - 作为整数，以三位一组数字
• total_bin - 作为带有二进制前缀的浮点数
• total_dec - 作为带有十进制前缀的浮点数

自定义项

(|state| EXPR)

显示给定函数的返回值，该函数接受 State 作为输入并返回 String。

(|s| custom_eta(s))     // "12h 34m 56s"

use ml_progress::State;

fn custom_eta(state: &State) -> String {
    if let Some(eta) = state.eta() {
        let (h, m, s) = ml_progress::duration_hms(eta);
        if h > 0 {
            format!("{}h {}m {}s", h, m, s)
        } else if m > 0 {
            format!("{}m {}s", m, s)
        } else {
            format!("{}s", s)
        }
    } else {
        "".to_string()
    }
}