TAAP

参数解析 - 简单易用

什么是 TAAP？

TAAP 是一个为 Rust 制作的参数解析器，以易用性为设计理念！

(TAAP 的缩写为 "totally acceptable argument parser")

此包提供 Argument 结构体，它有几个实现，您可以使用这些实现来创建和解析参数。要开始，请查看下面的示例，该示例使用此包创建了一个具有参数的简单程序！

(提示！所有这些，以及更多，都在 docs.rs 页面 上提供)

快速入门

添加到项目中

要将此包包含到您的项目中，请在您的 Cargo.toml 文件中添加以下行

[dependencies]
taap = "0.1.4"

或者，在您的 cargo 项目目录中运行此命令

cargo add taap

添加后，您就可以使用 TAAP 了！

示例用法

在下面的代码块中，我将介绍如何添加

• 一个位置参数
• 一个可选参数
• 一些退出状态
• 如何解析参数（并使用它们）（此示例/代码块也位于 示例文件夹 中）

// First, import taap so we can use it
use taap;

fn main() {
    // Next, in the main function, create a MUTABLE variable using Argument::new()
    let mut arguments = taap::Argument::new("example-1", "The first example program for TAAP!", "The text at the bottom of the help!", "SpamixOfficial 2023");


    // Now we will add our first positional argument!
    // First we add our letter we want to use, in this case 'f'
    // Next we add our long name we want to use, in this case "foo"
    // To add an argument without a "short name", set the short name to '-' or ' '
    arguments.add_option('f', "foo", "0", Some("Some help!"));
    arguments.add_option('-', "no-help", "2", None);


    // Here I'll add a positonal argument. Positional arguments takes almost the same parameters as
    // optional arguments, except that it doesn't take a "long name" and a "short name". Instead it
    // just takes a placeholder 
    arguments.add_arg("BAR", "1", None);

    // Now let's also add some exit statuses! 
    arguments.add_exit_status(0, "Everything went just fine");
    arguments.add_exit_status(1, "Something went a little wrong");
    arguments.add_exit_status(2, "Something went horribly wrong!");

    // Finally, let's parse the args and make use of them!
    //
    // We parse the args by calling parse_args(), which returns a HashMap<String, (bool, String)>
    // I'll explain what every part means in a second!
    //
    // When we have parsed our args, we also want to save the result! 
    // To do this we create a new variable, and contain our parsed args in that variable 
    // If we want to use a custom argument-list we can pass it using Some(Vec<String>)
    // In this case we don't want to do that, so we pass None
    let parsed_arguments = arguments.parse_args(None);
    

    // Now let's use our arguments!
    // First, let's grab our first positional argument, named "BAR"
    let bar = parsed_arguments.get("BAR").unwrap();
    println!("BAR is: {}", bar.0);

    // Next, let's see if our optional argument foo was used
    //
    // The process here is the same as the previous lines
    // If your optional argument take no arguments, then your Vec<String> will be an empty vector
    let foo = parsed_arguments.get("f").unwrap();
    was_foo_used(foo);

    // Finally, let's see how we would handle an output with values!
    
    let no_help = parsed_arguments.get("no-help").unwrap();
    if no_help.0 {
        println!("--no-help was used with arguments:");
        for argument in no_help.1.iter() {
            println!("{}", argument);
        };
    } else {
        println!("--no--help was not used!");
    };
}

fn was_foo_used(info: &(bool, Vec<String>)) {
    // As you see here, we use info.0 to retreive if foo was used or not, which is a boolean value
    if info.0 {
        println!("Foo was used!");
    } else {
        println!("Foo was not used!");
    };
}

如果您想了解更多“深入”的解释和注释，请参阅 GitHub 仓库中示例文件夹中的第一个示例

使用您的软件

现在让我们运行我们的程序！

[user@the_machine taap-rs]$ ./example-1
Error! BAR requires 1 arguments,

我们没有提供任何参数，这导致了这个输出！

现在让我们实际提供参数。为了做到这一点，我们可能首先想看看帮助信息！

[user@the_machine taap-rs]$ ./example-1 -h
Usage: example-1 BAR [OPTIONS]
The first example program for TAAP!

Positional Arguments:
    BAR		

Options:
    -h	--help		Use this to print this help message
    -f	--foo		Some help!
     	--no-help*2		

Exit Statuses:
    0	Everything went just fine
    1	Something went a little wrong
    2	Something went horribly wrong!

The text at the bottom of the help!
SpamixOfficial 2023

嗯，我们没有定义帮助参数，不过，如您从上面的输出中看到的，TAAP 已经为我们处理了这一点！

当我们添加参数时，它也会自动将其添加到帮助信息中。如果您也想自己打印帮助信息，可以调用 print_help() 函数！

现在让我们用正确的参数运行程序！

[user@the_machine taap-rs]$ ./example-1 "I am BAR" -f Im_foo --no-help "I take" "Two arguments!"
BAR is: true
Foo was used!
--no-help was used with arguments:
I take
Two arguments! 

如您所见，所有参数都得到了正确解析和使用！

额外信息

如果其中一个参数会有一个未指定的参数数量（无限数量），我们可能需要使用 - 来终止它。

这意味着，如果 BAR 有无限数量的参数，它将被 -f 选项终止，因为字符 - 用于终止无限参数。

如果我们还想使用破折号（-），就必须用反斜杠（\）来转义它。

注意：一些shell实际上使用反斜杠（\）作为转义字符，这意味着你需要转义转义字符（\\）。

结束语

你现在应该准备好使用TAAP了！

想了解更多关于TAAP的信息，请查看docs.rs上的更多文档

想看更多示例，请查看这个仓库中的示例文件夹

致谢

查看CREDITS.md以了解致谢信息