Rust命令行参数解析库clap-adapters使用指南

clap-adapters是一个为Rust命令行参数解析库clap提供扩展功能的库，它添加了适配器和自定义参数处理功能，增强了clap的灵活性。

主要功能

1. 提供多种参数适配器
2. 支持自定义参数处理
3. 简化复杂参数配置
4. 增强错误处理能力

安装

在Cargo.toml中添加依赖：

[dependencies]
clap = { version = "4.0", features = ["derive"] }
clap-adapters = "0.1"

基本使用方法

1. 使用预定义适配器

use clap::{Parser, Subcommand};
use clap_adapters::prelude::*;

#[derive(Parser)]
struct Args {
    #[clap(adapter = Trim)]
    name: String,
    
    #[clap(adapter = Lowercase)]
    category: String,
    
    #[clap(adapter = ParseNumber)]
    count: u32,
}

fn main() {
    let args = Args::parse();
    println!("Name: {}, Category: {}, Count: {}", args.name, args.category, args.count);
}

2. 自定义适配器

use clap::{Parser, Subcommand};
use clap_adapters::{Adapter, AdapterResult};

struct Capitalize;

impl Adapter for Capitalize {
    type Target = String;
    
    fn adapt(&self, input: &str) -> AdapterResult<Self::Target> {
        if input.is_empty() {
            return Err("Input cannot be empty".into());
        }
        let mut chars = input.chars();
        let first = chars.next().unwrap().to_uppercase().collect::<String>();
        let rest = chars.collect::<String>();
        Ok(format!("{}{}", first, rest))
    }
}

#[derive(Parser)]
struct Args {
    #[clap(adapter = Capitalize)]
    username: String,
}

fn main() {
    let args = Args::parse();
    println!("Username: {}", args.username);  // 输入"john"会输出"John"
}

3. 组合适配器

use clap::Parser;
use clap-adapters::{prelude::*, AdapterChain};

#[derive(Parser)]
struct Args {
    #[clap(adapter = AdapterChain::new()
        .add(Trim)
        .add(Lowercase)
        .add(Capitalize))]
    city: String,
}

内置适配器

clap-adapters提供了一些常用的内置适配器：

• Trim: 去除字符串两端的空白字符
• Lowercase: 转换为小写
• Uppercase: 转换为大写
• ParseNumber: 解析为数字类型
• ParseBool: 解析为布尔值
• Split: 按分隔符分割字符串
• Collect: 收集多个值到集合

高级用法

自定义错误处理

use clap_adapters::{Adapter, AdapterResult};

struct EvenNumber;

impl Adapter for EvenNumber {
    type Target = i32;
    
    fn adapt(&self, input: &str) -> AdapterResult<Self::Target> {
        let num = input.parse::<i32>()?;
        if num % 2 == 0 {
            Ok(num)
        } else {
            Err("Number must be even".into())
        }
    }
}

复杂参数处理

use clap::Parser;
use clap_adapters::{prelude::*, AdapterChain};
use serde_json::Value;

#[derive(Parser)]
struct ConfigArgs {
    #[clap(
        long,
        adapter = AdapterChain::new()
            .add(Trim)
            .add(ParseJson)
    )]
    config: Value,
}

完整示例代码

下面是一个结合了多种功能的完整示例：

use clap::Parser;
use clap_adapters::{prelude::*, Adapter, AdapterResult, AdapterChain};
use serde_json::Value;

// 自定义适配器 - 将字符串转为大写并添加前缀
struct PrefixAdapter;

impl Adapter for PrefixAdapter {
    type Target = String;
    
    fn adapt(&self, input: &str) -> AdapterResult<Self::Target> {
        Ok(format!("USER_{}", input.to_uppercase()))
    }
}

// 主命令参数结构体
#[derive(Parser, Debug)]
#[command(name = "app", version = "1.0", about = "clap-adapters演示程序")]
struct Cli {
    // 使用预定义Trim适配器
    #[clap(short, long, adapter = Trim)]
    name: String,
    
    // 使用预定义ParseNumber适配器
    #[clap(short, long, adapter = ParseNumber)]
    age: u32,
    
    // 使用自定义适配器
    #[clap(short, long, adapter = PrefixAdapter)]
    id: String,
    
    // 使用适配器链
    #[clap(
        long,
        adapter = AdapterChain::new()
            .add(Trim)
            .add(Lowercase)
    )]
    city: String,
    
    // 复杂参数处理
    #[clap(
        long,
        adapter = AdapterChain::new()
            .add(Trim)
            .add(ParseJson)
    )]
    config: Option<Value>,
}

fn main() {
    let args = Cli::parse();
    println!("解析后的参数: {:?}", args);
    
    println!("\n示例用法:");
    println!("cargo run -- --name \"  John Doe  \" --age 30 --id johndoe --city \"NEW YORK\" --config '{\"key\":\"value\"}'");
}

注意事项

1. 适配器会按照添加顺序依次执行
2. 错误消息会传递给clap的错误处理系统
3. 复杂的适配器链可能会影响性能
4. 适配器只能用于字段参数，不能用于命令或子命令

clap-adapters为clap提供了更强大的参数处理能力，特别适合需要复杂参数转换和验证的场景。