Rustのclapにおける引数定義とhelp内のUSAGE表記の調査

今回は、Rustのclapについて、コマンドライン引数の定義によってhelpの際に出てくるUSAGEの書かれ方がどう変わるかを調査してみました。

なお、tomlファイルの依存関係は以下のように記載しています。

[dependencies]
clap = { version = "3.0.6", features = ["derive"] }

さて、まずは以下のような定義です。下の例はtextと名前をつけたstring型の引数が必要な状態です。

use clap::Parser;

#[derive(Parser)]
struct Config {
    text: String,
}

fn main() {
    let config = Config::parse();
}

こちらでcargo run -- -helpとしてどのように書かれるかというと

...
USAGE:
    rust.exe <TEXT>
...

次に、先ほどtextの定義をtext: Option<String>,と、引数になくても問題がない（エラーにならない）ように変更して同じようにhelpを表示させてみます。

...
USAGE:
    rust.exe [TEXT]
...

ここで注目してもらいたいのはUSAGEに書かれた部分です。最初のように、引数が必要（＝引数に書かないとエラーになる）ような定義の時のUSAGEは、<TEXT>のように<>で囲まれています。そして引数がなくてもエラーにならないにすると、この部分が[text]と、[]で囲まれています。

つまり、その引数が必須の場合は<>で囲み、任意の場合は[]で囲むのが表記上のルールのようです。

さて、次はtextの定義をtext: Vec<String>,としてみましょう。これは引数を複数指定することができ、また、引数に何もなくてもエラーになりません。これでhelpを表示させると

...
USAGE:
    rust.exe [TEXT]...
...

また少し変わりました。引数に何もなくてもエラーにならないような定義にしたので[]になっていますが、今回は後ろに...がついています。これが「複数指定することが可能」という意味になっているようです。

まとめると次のようになりそうです。

• 引数が必須の場合は<>で囲まれる
• 引数が任意（必須でない）場合は[]で囲まれる
• 引数が複数指定可能の場合は...がつく

もしclapを使わず自分でCLIツールを作ることがあった場合に、USAGEの書き方の1つの参考になるかなぁと思いました。