Brasp 文档

概述

Brasp 是一个 Rust 库，专为处理命令行应用程序的配置解析而设计。它提供了一种定义配置选项、解析命令行参数、验证输入值和管理来自环境变量的默认值的方法。

功能

• 定义字符串、数字和布尔类型的选项。
• 支持选项的单值和多值。
• 自动验证输入值。
• 能够从环境变量设置默认值。
• 支持短选项和长命令行选项。

安装

将以下内容添加到您的 Cargo.toml

[dependencies]
brasp = "0.1.2"

使用方法

基本设置

导入所需的模块并创建一个 Brasp 实例。

use std::env;
use std::collections::HashMap;
use brasp::{Brasp, BraspOptions, ValidValue, ConfigOptionBase, Validator};

fn main() {
    let args: Vec<String> = env::args().collect();
    
    let mut brasp = Brasp {
        config_set: HashMap::new(),
        short_options: HashMap::new(),
        options: BraspOptions {
            allow_positionals: true,
            env_prefix: Some("MYAPP".to_string()),
            usage: None,
        },
    };

    // Define options and flags here
}

定义选项

可以使用可用方法定义选项

• opt 用于字符串选项。
• num 用于数值选项。
• flag 用于布尔选项。

每个选项都可以有短名称、默认值、描述和验证。

brasp.opt(HashMap::from([(
    "config".to_string(),
    ConfigOptionBase {
        config_type: "string".to_string(),
        short: Some("c".to_string()),
        default: None,
        description: Some("Configuration file path".to_string()),
        validate: Some(Validator::None),
        multiple: false,
    },
)]));

brasp.flag(HashMap::from([(
    "verbose".to_string(),
    ConfigOptionBase {
        config_type: "boolean".to_string(),
        short: Some("v".to_string()),
        default: Some(ValidValue::Boolean(false)),
        description: Some("Enable verbose output".to_string()),
        validate: Some(Validator::None),
        multiple: false,
    },
)]));

解析命令行参数

要解析命令行参数，请使用 parse_raw 方法。这将返回一个包含解析值和位置参数的 OptionsResult。

let parsed_values = brasp.parse_raw(args[1..].to_vec());

if let Some(config) = parsed_values.values.get("config") {
    println!("Config value: {}", config);
}

if let Some(verbose) = parsed_values.values.get("verbose") {
    println!("Verbose mode: {}", verbose);
} else {
    println!("Verbose mode is off");
}

验证选项

使用 validate 方法验证解析值是否与定义的选项相匹配。

if let Err(e) = brasp.validate(&parsed_values.values) {
    eprintln!("Validation error: {}", e);
}

从环境变量设置默认值

如果已设置，您可以填充来自环境变量的默认值。

brasp.set_defaults_from_env();

完整示例

以下是一个使用 Brasp 的完整命令行应用程序示例

use std::env;
use std::collections::HashMap;
use brasp::{Brasp, BraspOptions, ValidValue, ConfigOptionBase, Validator};

fn main() {
    let args: Vec<String> = env::args().collect();
    
    let mut brasp = Brasp {
        config_set: HashMap::new(),
        short_options: HashMap::new(),
        options: BraspOptions {
            allow_positionals: true,
            env_prefix: Some("MYAPP".to_string()),
            usage: None,
        },
    };

    brasp.opt(HashMap::from([(
        "config".to_string(),
        ConfigOptionBase {
            config_type: "string".to_string(),
            short: Some("c".to_string()),
            default: None,
            description: Some("Configuration file path".to_string()),
            validate: Some(Validator::None),
            multiple: false,
        },
    )]));

    brasp.flag(HashMap::from([(
        "verbose".to_string(),
        ConfigOptionBase {
            config_type: "boolean".to_string(),
            short: Some("v".to_string()),
            default: Some(ValidValue::Boolean(false)),
            description: Some("Enable verbose output".to_string()),
            validate: Some(Validator::None),
            multiple: false,
        },
    )]));

    let parsed_values = brasp.parse_raw(args[1..].to_vec());

    if let Some(config) = parsed_values.values.get("config") {
        println!("Config value: {}", config);
    }

    if let Some(verbose) = parsed_values.values.get("verbose") {
        println!("Verbose mode: {}", verbose);
    } else {
        println!("Verbose mode is off");
    }

    if let Some(usage) = brasp.options.usage.clone() {
        println!("{}", usage);
    }
}

高级功能

多值

您可以定义接受多个值的选项。

brasp.opt_list(HashMap::from([(
    "include".to_string(),
    ConfigOptionBase {
        config_type: "string".to_string(),
        short: Some("I".to_string()),
        default: None,
        description: Some("Directories to include".to_string()),
        validate: Some(Validator::None),
        multiple: true,
    },
)]));

使用正则表达式和范围进行验证

您可以使用正则表达式对字符串进行验证或对数字进行范围检查。

use regex::Regex;

brasp.opt(HashMap::from([(
    "pattern".to_string(),
    ConfigOptionBase {
        config_type: "string".to_string(),
        short: Some("p".to_string()),
        default: None,
        description: Some("Pattern to match".to_string()),
        validate: Some(Validator::Regex("^[a-z]+$".to_string())),
        multiple: false,
    },
)]));

brasp.num(HashMap::from([(
    "level".to_string(),
    ConfigOptionBase {
        config_type: "number".to_string(),
        short: Some("l".to_string()),
        default: Some(ValidValue::Number(3)),
        description: Some("Level value".to_string()),
        validate: Some(Validator::NumberRange(1, 5)),
        multiple: false,
    },
)]));

环境变量

要设置来自环境变量的默认值，请定义前缀并调用 set_defaults_from_env。

env::set_var("MYAPP_CONFIG", "default_config.yaml");

let mut brasp = Brasp {
    config_set: HashMap::new(),
    short_options: HashMap::new(),
    options: BraspOptions {
        allow_positionals: true,
        env_prefix: Some("MYAPP".to_string()),
        usage: None,
    },
};

// Define options...

brasp.set_defaults_from_env();

设置用法信息

您可以定义自定义用法信息，当需要时将显示。

brasp.options.usage = Some("Usage: myapp [options]".to_string());

if let Some(usage) = brasp.options.usage.clone() {
    println!("{}", usage);
}

// Or handling help flag

贡献

提交一个 pull request，提交您的 PR，我将进行审查。欢迎贡献！ :)