示例

以下是一个完整的示例，展示了如何编写支持一些命令行选项的程序。它还展示了处理器如何修改其状态，从而实现具有状态和条件选项处理。

use ap::{App, Arg, Args, Handler, Need, Result};

// The type that will be used to handle all the CLI options
// for this program.
#[derive(Clone, Debug, Default)]
struct MyHandler {
    i: usize,
    v: Vec<String>,
    s: String,
}

impl Handler for &mut MyHandler {
    fn handle(&mut self, arg: Arg) -> Result<()> {
        println!(
            "option: {:?}, value: {:?}, count: {}",
            arg.option, arg.value, arg.count
        );

        // Change behaviour if user specified '-d'
        if arg.option == 'd' {
            self.i += 7;
        } else {
            self.i += 123;
        }

        self.s = "string value set by handler".into();
        self.v.push("vector modified by handler".into());

        Ok(())
    }
}

fn main() -> Result<()> {
    let mut handler = MyHandler::default();

    println!("Initial state of handler: {:?}", handler);

    let mut args = Args::default();

    // Support "-a <value>" option.
    args.add(Arg::new('a').needs(Need::Argument));

    // Support "-b <value>" option.
    args.add(Arg::new('b').needs(Need::Argument));

    // Support "-d" flag option.
    args.add(Arg::new('d'));

    let mut args = App::new("my app")
        .help("some text")
        .args(args)
        .handler(Box::new(&mut handler));

    // Parse the command-line
    let result = args.parse();

    // If you want to inspect the handler after parsing, you need to
    // force ownership to be returned by dropping the `Args` variable.
    drop(args);

    println!("Final state of handler: {:?}", handler);

    // return value
    result
}

对于更多示例，请尝试 examples/ 目录中的程序

$ cargo run --example simple -- -a foo -d -a bar -d -a baz
$ cargo run --example positional-args-only -- one two "hello world" three "foo bar" four "the end"
$ cargo run --example option-and-positional-args -- "posn 1" -d "posn 2" -a "hello world" -a "foo bar" "the end" -d
$ cargo run --example error-handler -- -a -e -i -o -u

细节

术语

注意：有关更多详细信息，请参阅 getopt(3)。

• “参数”是指在命令行上传递给程序的值。

  参数可以是“选项”或“位置参数”。

  注意：单引号或双引号内的字符串被视为一个参数，即使该字符串包含多个单词（这种魔法由 shell 处理）。

• “选项”是以下划线字符（-）开头并以单个字符结尾的参数，该字符本身不是 -，例如，-a、-z、-A、-Z、-0、-9、等等。

  该字符是选项的“名称”。选项名称区分大小写：大写和小写字母代表不同的选项。

  这种类型的选项被称为“短选项”，因为它只由一个字符识别。

• 接受参数（一个称为“选项参数”或“optarg”的值）的选项通常简单地称为“选项”，因为这是最常见的选项形式。

• “选项参数”是紧跟在选项后面的值。它被认为是“绑定”或与前面的选项配对。根据定义，选项参数不能以下划线开头，以避免被视为自己的选项。

• 不接受参数的选项称为“标志”或“独立选项”。这些通常用于切换某些功能的开启或关闭。

  标志示例

  大多数程序支持一些常见的标志

  • -h：显示帮助/使用说明并退出。
  • -v：显示版本号并退出，或有时启用详细模式。

• “位置参数”（也称为“非选项参数”）不是选项的参数：它是一个单词或一个引号内的字符串（该字符串不能以下划线开头，除非它被转义为 \-）。

  位置参数示例

  echo(1) 是处理位置参数的程序的良例

  $ echo one two three "hello, world" four five "the end"
  

• 特殊选项 -- 保留用于表示“所有选项的结束”：它可以由需要接受一组选项后跟一组位置参数的程序使用。即使双横线后的参数以下划线开头，它也不会被视为选项。

  如果该包在命令行上找到 --，它将停止处理命令行参数。

参数类型示例

假设一个程序按照以下方式运行：

$ myprog -d 371 "hello, world" -x "awesome value" -v "the end"

该程序有7个实际的命令行参数。

1: '-d'
2: '371'
3: 'hello, world'
4: '-x'
5: 'awesome value'
6: '-v'
7: 'the end'

这些参数的解析方式取决于每个选项（以-开头的参数）是否指定了取值。

如果所有选项都指定为标志，则参数的解析方式如下：

'-d'            # A flag option.
'371'           # A positional argument.
'hello, world'  # A positional argument.
'-x'            # A flag option.
'awesome value' # A positional argument.
'-v'            # A flag option.
'the end'       # A positional argument.

但是，如果我们假设-d和-x被指定为取值，那么参数分组如下：

'-d 371'           # An option ('d') with a numeric option argument ('371').
'hello, world'     # A positional argument ('hello, world').
'-x awesome value' # An option ('x') with a string option argument ('awesome value').
'-v'               # A flag option.
'the end'          # A positional argument.

'-d 371'             # An option ('d') with a numeric option argument ('371').
'hello, world'       # A positional argument ('hello, world').
'-x 'awesome value'' # An option ('x') with a string option argument ('awesome value').
'-v 'the end''       # An option('v') with a string option argument ('the end').

#
let mut args = Args::default();

args.add(Arg::new('1'));
args.add(Arg::new('2').needs(Need::Argument));

$ prog -2 -1