Rust命令行工具生成库make-cmd使用指南

简介

make-cmd是一个Rust库，用于快速构建高效且可扩展的命令行接口(CLI)应用程序。它简化了命令行参数解析、子命令管理和帮助文档生成的过程，让开发者能专注于业务逻辑的实现。

主要特性

• 简洁的API设计
• 自动生成帮助文档
• 支持嵌套子命令
• 类型安全的参数解析
• 可扩展的命令结构

安装

在Cargo.toml中添加依赖：

[dependencies]
make-cmd = "0.1"

基本使用方法

1. 创建简单命令

use make_cmd::Command;

fn main() {
    let cmd = Command::new("greet")
        .about("A simple greeting application")
        .version("1.0.0")
        .arg("name", "The person to greet")
        .action(|args| {
            let name = args.get_one::<String>("name").unwrap();
            println!("Hello, {}!", name);
            Ok(())
        });
    
    cmd.run();
}

运行示例：

$ greet Rust
Hello, Rust!

2. 创建带子命令的应用

use make_cmd::{Command, SubCommand};

fn main() {
    let cmd = Command::new("file-manager")
        .about("A simple file manager")
        .version("1.0.0")
        .subcommand(
            SubCommand::new("create")
                .about("Create a new file")
                .arg("filename", "Name of the file to create")
                .action(|args| {
                    let filename = args.get_one::<String>("filename").unwrap();
                    std::fs::File::create(filename)?;
                    println!("Created file: {}", filename);
                    Ok(())
                })
        )
        .subcommand(
            SubCommand::new("delete")
                .about("Delete a file")
                .arg("filename", "Name of the file to delete")
                .action(|args| {
                    let filename = args.get_one::<String>("filename").unwrap();
                    std::fs::remove_file(filename)?;
                    println!("Deleted file: {}", filename);
                    Ok(())
                })
        );
    
    cmd.run();
}

运行示例：

$ file-manager create test.txt
Created file: test.txt

$ file-manager delete test.txt
Deleted file: test.txt

3. 添加可选参数和标志

use make_cmd::Command;

fn main() {
    let cmd = Command::new("calculator")
        .about("A simple calculator")
        .version("1.0.0")
        .arg("x", "First number")
        .arg("y", "Second number")
        .flag("add", "Add the numbers")
        .flag("multiply", "Multiply the numbers")
        .action(|args| {
            let x: f64 = args.get_one("x").unwrap();
            let y: f64 = args.get_one("y").unwrap();
            
            if args.is_present("add") {
                println!("Result: {}", x + y);
            } else if args.is_present("multiply") {
                println!("Result: {}", x * y);
            } else {
                println!("Please specify an operation (--add or --multiply)");
            }
            
            Ok(())
        });
    
    cmd.run();
}

运行示例：

$ calculator 5 3 --add
Result: 8

$ calculator 5 3 --multiply
Result: 15

高级用法

1. 自定义参数解析器

use make_cmd::{Command, Arg};
use std::str::FromStr;

struct Point {
    x: i32,
    y: i32,
}

impl FromStr for Point {
    type Err = String;
    
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let parts: Vec<&str> = s.split(',').collect();
        if parts.len() != 2 {
            return Err("Point must be in format 'x,y'".to_string());
        }
        Ok(Point {
            x: parts[0].parse().map_err(|_| "Invalid x coordinate".to_string())?,
            y: parts[1].parse().map_err(|_| "Invalid y coordinate".to_string())?,
        })
    }
}

fn main() {
    let cmd = Command::new("point-ops")
        .about("Point operations")
        .arg(Arg::new("point")
            .help("Point in format 'x,y'")
            .required(true)
            .parser::<Point>())
        .action(|args| {
            let point = args.get_one::<Point>("point").unwrap();
            println!("Point coordinates: ({}, {})", point.x, point.y);
            Ok(())
        });
    
    cmd.run();
}

运行示例：

$ point-ops 10,20
Point coordinates: (10, 20)

2. 异步命令处理

use make_cmd::Command;
use tokio::fs;

#[tokio::main]
async fn main() {
    let cmd = Command::new("async-file")
        .about("Async file operations")
        .arg("filename", "File to read")
        .async_action(|args| async move {
            let filename = args.get_one::<String>("filename").unwrap();
            let contents = fs::read_to_string(filename).await?;
            println!("File contents:\n{}", contents);
            Ok(())
        });
    
    cmd.run_async().await;
}

最佳实践

1. 模块化设计：将不同子命令的实现放在不同的模块中
2. 错误处理：使用anyhow或thiserror库进行友好的错误处理
3. 测试：为每个命令和子命令编写单元测试
4. 文档：为每个命令和参数添加详细的帮助文本
5. 性能：对于CPU密集型操作，考虑使用rayon进行并行处理

完整示例

下面是一个完整的文件管理工具示例，结合了基本和高级用法：

use make_cmd::{Command, SubCommand, Arg};
use std::path::PathBuf;
use anyhow::Result;

// 定义自定义文件大小类型
#[derive(Debug)]
struct FileSize(u64);

impl std::str::FromStr for FileSize {
    type Err = String;
    
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let size = s.parse().map_err(|_| "Invalid file size".to_string())?;
        Ok(FileSize(size))
    }
}

fn main() -> Result<()> {
    let cmd = Command::new("file-tool")
        .about("Advanced file management tool")
        .version("1.0.0")
        .subcommand(
            SubCommand::new("info")
                .about("Get file information")
                .arg(Arg::new("path")
                    .help("File path")
                    .required(true))
                .arg(Arg::new("human-readable")
                    .help("Show size in human readable format")
                    .short('h')
                    .long("human-readable")
                    .takes_value(false))
                .action(|args| {
                    let path = args.get_one::<String>("path").unwrap();
                    let metadata = std::fs::metadata(path)?;
                    
                    if args.is_present("human-readable") {
                        println!("Size: {} KB", metadata.len() / 1024);
                    } else {
                        println!("Size: {} bytes", metadata.len());
                    }
                    
                    Ok(())
                })
        )
        .subcommand(
            SubCommand::new("search")
                .about("Search files")
                .arg(Arg::new("directory")
                    .help("Directory to search")
                    .required(true))
                .arg(Arg::new("extension")
                    .help("File extension filter")
                    .short('e')
                    .long("extension"))
                .arg(Arg::new("min-size")
                    .help("Minimum file size in bytes")
                    .long("min-size")
                    .parser::<FileSize>())
                .async_action(|args| async move {
                    let dir = args.get_one::<String>("directory").unwrap();
                    let extension = args.get_one::<String>("extension");
                    let min_size = args.get_one::<FileSize>("min-size");
                    
                    // 异步文件搜索逻辑
                    search_files(dir, extension, min_size).await?;
                    
                    Ok(())
                })
        );
    
    cmd.run()?;
    Ok(())
}

async fn search_files(dir: &str, extension: Option<&String>, min_size: Option<&FileSize>) -> Result<()> {
    // 实现异步文件搜索逻辑
    println!("Searching in: {}", dir);
    println!("Filters - Extension: {:?}, Min Size: {:?}", extension, min_size);
    Ok(())
}

总结

make-cmd为Rust开发者提供了一个简单而强大的工具来构建CLI应用程序。通过其直观的API和丰富的功能，你可以快速创建出专业级的命令行工具，而无需花费大量时间处理参数解析和帮助文档生成等底层细节。