qsv_docopt

此 crate 主要维护用于 qsv 项目，因为其已针对 docopt 的自文档特性进行了优化，而 clap 和 structopt 都无法提供。

由于 docopt.rs 项目不再维护，此 crate 将进行更新，以确保 qsv 使用此 qsv 优化版本的 docopt 的最新特性和创新。

Rust 的 Docopt，具有基于自动类型解码（即数据验证）。此实现符合 官方 Docopt 描述 并 通过其测试套件。

双许可下 MIT 或 UNLICENSE。

文档

https://docs.rs/qsv_docopt

安装

此 crate 完全兼容 Cargo。只需将其添加到您的 Cargo.toml

[dependencies]
qsv_docopt = "1"
serde = { version = "1", features = ["derive"] }

快速示例

这是一个完整的工作示例。请注意，您可以在 Docopt 使用字符串中指定每个命名值的类型。值将被自动转换为这些类型（或报告错误）。

use qsv_docopt::Docopt;
use serde::Deserialize;

const USAGE: &'static str = "
Naval Fate.

Usage:
  naval_fate.py ship new <name>...
  naval_fate.py ship <name> move <x> <y> [--speed=<kn>]
  naval_fate.py ship shoot <x> <y>
  naval_fate.py mine (set|remove) <x> <y> [--moored | --drifting]
  naval_fate.py (-h | --help)
  naval_fate.py --version

Options:
  -h --help     Show this screen.
  --version     Show version.
  --speed=<kn>  Speed in knots [default: 10].
  --moored      Moored (anchored) mine.
  --drifting    Drifting mine.
";

#[derive(Debug, Deserialize)]
struct Args {
    flag_speed: isize,
    flag_drifting: bool,
    arg_name: Vec<String>,
    arg_x: Option<i32>,
    arg_y: Option<i32>,
    cmd_ship: bool,
    cmd_mine: bool,
}

fn main() {
    let args: Args = Docopt::new(USAGE)
        .and_then(|d| d.deserialize())
        .unwrap_or_else(|e| e.exit());
    println!("{:?}", args);
}

结构字段名映射

结构的字段名映射如下

-g            => flag_g
--group       => flag_group
--group <arg> => flag_group
FILE          => arg_FILE
<file>        => arg_file
build         => cmd_build

传统 Docopt API

Docopt的参考实现返回一个名为<arg>或--flag的Python字典。如果您更喜欢这种访问模式，则可以使用docopt::ArgvMap。缺点是您必须手动进行所有类型转换。以下是一个使用哈希表的经典Docopt示例

use qsv_docopt::Docopt;

const USAGE: &'static str = "
Naval Fate.

Usage:
  naval_fate.py ship new <name>...
  naval_fate.py ship <name> move <x> <y> [--speed=<kn>]
  naval_fate.py ship shoot <x> <y>
  naval_fate.py mine (set|remove) <x> <y> [--moored | --drifting]
  naval_fate.py (-h | --help)
  naval_fate.py --version

Options:
  -h --help     Show this screen.
  --version     Show version.
  --speed=<kn>  Speed in knots [default: 10].
  --moored      Moored (anchored) mine.
  --drifting    Drifting mine.
";

fn main() {
    let args = Docopt::new(USAGE)
                      .and_then(|dopt| dopt.parse())
                      .unwrap_or_else(|e| e.exit());
    println!("{:?}", args);

    // You can conveniently access values with `get_{bool,count,str,vec}`
    // functions. If the key doesn't exist (or if, e.g., you use `get_str` on
    // a switch), then a sensible default value is returned.
    println!("\nSome values:");
    println!("  Speed: {}", args.get_str("--speed"));
    println!("  Drifting? {}", args.get_bool("--drifting"));
    println!("  Names: {:?}", args.get_vec("<name>"));
}

支持Tab补全

这个特定的实现包含了一个名为docopt-wordlist的命令，可以用于自动化Tab补全。此存储库还收集了针对各种shell（目前仅限bash）的一些基本补全支持，存放在completions目录中。

您可以使用它们来设置系统上的Tab补全。它应该适用于任何使用Docopt的程序（或者更准确地说，任何输出类似于Docopt的使用信息的程序）。例如，为了获得Cargo的Tab补全支持，您需要安装docopt-wordlist并在您的$HOME/.bash_completion文件中添加一些咒语（这可能在其他shell中有所不同）。

以下是步骤分解

# Download and build `docopt-wordlist` (as part of the Docopt package)
$ git clone git://github.com/docopt/docopt.rs
$ cd docopt.rs
$ cargo build --release

# Now setup tab completion (for bash)
$ echo "DOCOPT_WORDLIST_BIN=\"$(pwd)/target/release/docopt-wordlist\"" >> $HOME/.bash_completion
$ echo "source \"$(pwd)/completions/docopt-wordlist.bash\"" >> $HOME/.bash_completion
$ echo "complete -F _docopt_wordlist_commands cargo" >> $HOME/.bash_completion

我的CSV工具包也得到支持

# shameless plug...
$ echo "complete -F _docopt_wordlist_commands xsv" >> $HOME/.bash_completion

请注意，这只是一个初步的尝试。我希望能做出一些改进

1. 在补全时考虑上下文。例如，应该只显示可以导致有效的Docopt匹配的补全。这可能很困难。（即，可能需要重新结构化Docopt的内部结构。）
2. 支持更多的shell。（我愿意接受关于这个问题的pull请求。我怀疑我很快会走出bash。）
3. 使Tab补全支持更加无缝。目前它通过交织文件/目录补全来实现，方式相当复杂。