概述

Argrust 是一个简单的参数解析器，可以执行复杂任务。

徽章

目录

• 安装

• 用法

  • 导入
  • 参数

• 示例

• 测试

安装

可以使用以下命令全局安装：

cargo install argrust

或者，可以仅为您自己的项目安装

cargo add argrust

用法

导入

use argrust::{Arguments, ArgumentDescription, FetchTypes};

代码描述

• Arguments：这是一个用于存储各种参数信息的结构体。

  pub struct Arguments {
      gotargs: Vec<String>,
      allargs: Vec<String>,
      arguments: Vec<String>,
      errors: Vec<String>,
      data: Vec<ArgumentDescription>,
      used: Vec<String>,
  }
  

  • gotargs：存储通过命令行接收到的所有参数。
  • allargs：存储您定义的所有参数。
  • arguments：存储在 gotargs 中接收到的并在 allargs 中定义的参数。
  • errors：存储错误信息（如果有）。
  • data：这是一个名为 ArgumentDescription 的自定义结构体向量。我们稍后会详细介绍。现在，只需理解它将存储关于参数的数据（如果提供的话）。
  • used：存储已被用户使用或访问过的参数。

• ArgumentDescription：这是一个用于描述参数的结构体。尽管提供关于参数的数据是可选的，但参数的简短对应形式是必需的。

  pub struct ArgumentDescription {
      name: String,
      description: String,
      shorter_counterpart: String,
  }
  

  • name：存储参数的名称。-> 可选
  • description：存储参数的简短描述。-> 可选
  • shorter_counterpart：存储主要参数的简短对应形式。例如，--abc 是主要参数，而 -a 是简短对应形式。-> 必需。

• FetchTypes：这是一个用于获取参数值的枚举。

  pub enum FetchTypes {
      Fetch(usize),
      TillLast,
      TillNext,
  }
  

  • Fetch(usize)：可以与 .fetch() 方法一起使用，您需要指定期望的值数量。假设有两个参数 -a 和 -b，并且它们作为 -

    some_program -a 1 2 -b 34 56
    

    然后，为了获取减号后面的值 1 和 2，你可以指定你期望获取 Fetch(2)。类似地，为了获取 34 和 56，你可以使用 TillLast 来获取字符串最后的所有参数。或者如果你不确定，只需使用 Fetch(2)。

定义参数和相关

参数可以按照以下方式定义

let mut args = Arguments::new(std::env::args().skip(1).collect);

以下行 std::env::args().skip(1).collect() 返回除了文件名之外传递给程序的参数列表。

添加参数:

let description_argument1 = ArgumentsDescription::new()
    .name("argument1") // this is optional
    .description("this is argument 1") // this is optional
    .short("-a"); // this is mandatory

args.add("--arg", description_argument1);

解析参数:

args.analyse(); // this will fill the Arguments.arguments if any 
                // argument is received that is defined by you

检查是否收到参数:

// suppose the argument -a was received. you can check it by two ways.

if args.ifarg("-a") { // or args.ifarg("--arg")
    // do something
}

// NOTE: the above function will make the above argument as "used".
// Which means the user is already done with it. More Functionalities
// will be added on this later on.

// To avoid marking the argument as used, use:

if args.ifarg_force("-a") {
    // do something
}

获取传递给参数的值:

// suppose the argument was $ some_program -a 1 2 3

// we are expecting 3 values for this.

let values: Vec<String> = args.fetch("-a", FetchTypes::Fetch(3));

// NOTE: if we are only expecting 2 values, then the last value
// will just be discarded.

// if the number of arguments expected is not known at the current time,
// you have two options -> FetchTypes::TillNext or FetchTypes::TillLast

// NOTE: if it is not known if the argument u are fetching for is in the
// middle or at the last, it is better to use FetchTypes::TillNext.
// It will try to find if this argument is in the middle or not.
// If it is in the middle, then it will fetch all the values between the
// argument and the next argument.
// And if it finds out that the argument is at the last, it will auto-rerun
// with FetchTypes::TillLast. Pretty Handy right!

// use this like:

let values: Vec<String> = args.fetch("--arg", FetchTypes::TillNext);

// NOTE: so if there is no next argument for '--arg', it will run again
// with FetchTypes::TillLast

// Suppose the position of the argument is known to be at the last,
// then simple use FetchTypes::TillLast

// This will fetch all the arguments till Last.

let values: Vec<String> = args.fetch("--arg", FetchTypes::TillLast);

从定义的参数中移除参数:

args.remove("-a"); // or args.remove("--arg")

// while defining let mut args = Arguments::new(...);, make sure
// to add "mut" or else, add() and remove() wont work.

获取参数数据:

// get from defined arguments:

// by number
let some_arg = args.get_arg_by_number(1); // this will return "--arg"

// by index
let some_arg = args.get_arg_by_index(0); // this will also return "--arg"

// get arg description
let some_arg_description = args.get_arg_description("--arg").get();

示例

让我们看看一段实际工作的代码来更好地理解这个概念

use argrust::{Arguments, ArgumentDescription, FetchTypes};
use std::env;

fn main() {
    let mut args = Arguments::new(env::args().skip(1).collect());

    args.add("--setup", ArgumentDescription::new().short("-s"));
    args.add("--init", ArgumentDescription::new().name("initialize").short("-i"));

    args.analyse();

    let mut setup_value = String::new();

    if args.ifarg("--setup") {
        // fetch setup value
        setup_value = args.fetch("-s", FetchTypes::TillLast);
        // rest of the code.
    } else if args.ifarg("-i") {
        // init code
    }

    // NOTE: here, --init and --setup are mutually exclusive
    // meaning: they cannot be used together.

    // if you dont want that and you want multiple simultaneous args,
    // write them individually:

    // if args.ifarg("--setup") {
    //     // fetch setup value
    //     setup_value = args.fetch("-s", FetchTypes::TillLast);
    //     // rest of the code.
    // }
    
    // if args.ifarg("-i") {
    //     // init code
    // }
}

注意：还有更多功能即将推出。

测试

• 自动

  为了测试这些功能，你可以在终端运行以下命令

  argrust --test
  

  注意：这将克隆github仓库 d33pster/argrust，在终端打开的地方创建一个名为 argrust 的新文件夹。此外，它将安装 gcl - 一个基于rust的cli工具，它是git clone命令的替代品。有关 gcl 的更多信息，请点击 [这里]。

  附加说明：如果使用 cargo add argrust 添加 argrust，则此功能将不起作用。请尝试手动模式或使用 cargo install argrust 安装。

• 手动

  在新终端中运行以下命令

  git clone https://github.com/d33pster/argrust.git
  cd argrust
  cargo test