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つの参考になるかなぁと思いました。