Rust / 系统课时

解析命令行选项

解析命令行选项

命令行程序需要稳定地处理选项、默认值、子命令和帮助信息。本节使用 clap 的 derive API 定义一个小型任务工具,让参数结构直接映射为 Rust 类型,并由库统一完成解析与错误提示。

学习目标

  • 用 Parser 和 Subcommand 把命令行结构声明为 Rust 类型。
  • 为选项设置短名、长名和默认值,并读取子命令参数。
  • 使用自动生成的 --help 验证接口,并理解解析失败时的行为。

定义命令行接口

clap 的 derive 模式把命令行协议写在结构体和枚举上:顶层结构体保存全局选项,枚举表示互斥子命令,字段类型决定参数如何解析。这样业务代码拿到的是已经校验过的 Rust 值,不必手写字符串切分。

先在 Cargo.toml 中加入依赖:

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:

rust
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 只能选择一个。

运行一个带显式选项的子命令:

bash
cargo run --quiet -- --retries 5 add "write docs" --done

预期输出:

text
add title=write docs done=true retries=5

再验证默认值:

bash
cargo run --quiet -- list

预期输出:

text
list limit=10 retries=3

检查帮助信息与解析失败

clap 会根据类型和属性自动生成帮助信息。通过 Cargo 运行程序时,前一个 -- 用来结束 Cargo 自身的参数解析,后面的 --help 才会传给应用:

bash
cargo run --quiet -- --help

预期输出的关键内容包含:

text
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 中继续堆字符串判断。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

解析命令行选项

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通