Rust / 系统课时
解析命令行选项
解析命令行选项
命令行程序需要稳定地处理选项、默认值、子命令和帮助信息。本节使用 clap 的 derive API 定义一个小型任务工具,让参数结构直接映射为 Rust 类型,并由库统一完成解析与错误提示。
学习目标
- 用
Parser和Subcommand把命令行结构声明为 Rust 类型。 - 为选项设置短名、长名和默认值,并读取子命令参数。
- 使用自动生成的
--help验证接口,并理解解析失败时的行为。
定义命令行接口
clap 的 derive 模式把命令行协议写在结构体和枚举上:顶层结构体保存全局选项,枚举表示互斥子命令,字段类型决定参数如何解析。这样业务代码拿到的是已经校验过的 Rust 值,不必手写字符串切分。
先在 Cargo.toml 中加入依赖:
[package]
name = "tasker"
version = "0.1.0"
edition = "2021"
[dependencies]
clap = { version = "4", features = ["derive"] }生效行为:启用 derive 后可以使用 #[derive(Parser)] 与 #[derive(Subcommand)]。可用 cargo check --quiet 验证依赖解析是否成功;命令成功时没有终端输出。
实现选项、子命令和默认值
将下面代码保存为 src/main.rs:
use clap::{Parser, Subcommand};
#[derive(Parser, Debug)]
#[command(
name = "tasker",
version = "1.0.0",
about = "Manage local tasks",
disable_help_subcommand = true
)]
struct Cli {
/// Retry count shared by all subcommands.
#[arg(short, long, default_value_t = 3)]
retries: u8,
#[command(subcommand)]
command: Commands,
}
#[derive(Subcommand, Debug)]
enum Commands {
/// Add one task.
Add {
title: String,
#[arg(short, long, default_value_t = false)]
done: bool,
},
/// List tasks.
List {
#[arg(long, default_value_t = 10)]
limit: usize,
},
}
fn main() {
let cli = Cli::parse();
match cli.command {
Commands::Add { title, done } => {
println!("add title={title} done={done} retries={}", cli.retries);
}
Commands::List { limit } => {
println!("list limit={limit} retries={}", cli.retries);
}
}
}预期结果:源码能够编译;retries 未提供时取 3,list --limit 未提供时取 10,add 和 list 只能选择一个。
运行一个带显式选项的子命令:
cargo run --quiet -- --retries 5 add "write docs" --done预期输出:
add title=write docs done=true retries=5再验证默认值:
cargo run --quiet -- list预期输出:
list limit=10 retries=3检查帮助信息与解析失败
clap 会根据类型和属性自动生成帮助信息。通过 Cargo 运行程序时,前一个 -- 用来结束 Cargo 自身的参数解析,后面的 --help 才会传给应用:
cargo run --quiet -- --help预期输出的关键内容包含:
Usage: tasker [OPTIONS] <COMMAND>
Commands:
add
list
Options:
-r, --retries <RETRIES>
-h, --help
-V, --version帮助文本的空格对齐和说明文字会随 clap 小版本略有变化,但命令、选项名和默认值语义应保持一致。
如果用户输入未知子命令、无法转换成 u8 的 --retries,或缺少 add 所需的 title,Cli::parse() 会打印解析错误并以失败状态退出,业务分支不会执行。需要把解析错误转成自定义错误对象时,再改用 Cli::try_parse()。
把参数协议集中在类型定义中后,命令行帮助、类型校验和业务分发就能保持一致;新增子命令时优先扩展 Commands,而不是在 main 中继续堆字符串判断。