rust-clap

Rust Clap のベストプラクティス

clap を使用して Rust で CLI アプリケーションを構築するための包括的なベストプラクティスガイドです。8 つのカテゴリにわたる 42 のルールを収録し、CLI の設計、引数の解析、テストを導くために、影響度の高い順に優先順位を付けています。

適用する場面

次の場合に、これらのガイドラインを参照してください。

• Rust の新しい CLI アプリケーションを設計するとき
• 既存の CLI に引数やサブコマンドを追加するとき
• コマンドライン入力を検証、解析するとき
• CLI ツールの統合テストを作成するとき
• ヘルプテキストやユーザーエクスペリエンスを改善するとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	型駆動設計	重大	type-
2	Derive API のパターン	重大	derive-
3	引数の設定	高	arg-
4	検証と解析	高	valid-
5	サブコマンドのアーキテクチャ	中〜高	subcmd-
6	ヘルプとドキュメント	中	help-
7	エラー処理	中	error-
8	テストのパターン	低〜中	test-

クイックリファレンス

1. 型駆動設計（重大）

• type-valueenum-enums - 列挙型の引数には ValueEnum を使用する
• type-option-optional - 本当に省略可能な引数には Option を使用する
• type-pathbuf-files - ファイルシステムの引数には PathBuf を使用する
• type-vec-multiple - 複数の値を取る引数には Vec を使用する
• type-newtype-semantic - 意味を区別するにはニュータイプを使用する
• type-bool-flags - 単純なフラグには bool を使用する

2. Derive API のパターン（重大）

• derive-parser-entry - CLI のエントリーポイントには Parser を derive する
• derive-command-metadata - メタデータには Command 属性を使用する
• derive-subcommand-enum - コマンド階層には Subcommand derive を使用する
• derive-args-reusable - 再利用可能な引数グループには Args を derive する
• derive-doc-comments - ヘルプテキストにはドキュメントコメントを使用する
• derive-global-options - サブコマンド間で共通のオプションには Global を使用する
• derive-propagate-version - サブコマンドにバージョンを引き継ぐ

3. 引数の設定（高）

• arg-default-value - 適切なデフォルト値には default_value を使用する
• arg-env-fallback - 環境変数をフォールバックとして使用するには env を使用する
• arg-short-long - 短い形式と長い形式の両方のオプション名を用意する
• arg-conflicts-with - 相互に排他的なオプションには conflicts_with を使用する
• arg-requires - 依存関係のある引数には requires を使用する
• arg-value-name - 説明的なプレースホルダーには value_name を使用する

4. 検証と解析（高）

• valid-value-parser - カスタム検証には value_parser を使用する
• valid-possible-values - 文字列の制約には PossibleValuesParser を使用する
• valid-fromstr-types - ドメイン型には FromStr を実装する
• valid-try-parse - エラーを適切に処理するには try_parse を使用する
• valid-num-args - 値の個数を制限するには num_args を使用する

5. サブコマンドのアーキテクチャ（中〜高）

• subcmd-nested-hierarchy - 複雑な CLI にはネストされたサブコマンドを使用します
• subcmd-args-struct - サブコマンドの引数には構造体を使用します
• subcmd-required-help - サブコマンドを必須にするか、ヘルプを表示します
• subcmd-arg-groups - 複数の選択肢から 1 つを選ぶ要件には ArgGroup を使用します
• subcmd-external - プラグインシステムには外部サブコマンドを使用します

6. ヘルプとドキュメント（中）

• help-shell-completions - clap_complete でシェル補完を生成します
• help-next-heading - 整理されたヘルプには next_help_heading を使用します
• help-after-help - 例や補足情報には after_help を使用します
• help-hide-options - デフォルトのヘルプでは高度なオプションを非表示にします

7. エラー処理（中）

• error-exit-codes - 適切な終了コードを使用します
• error-context - エラーメッセージにコンテキストを追加します
• error-suggestions - 入力ミスに対する候補の提示を有効にします
• error-color-styles - エラーを見やすくするために色付きの出力を使用します

8. テストのパターン（低〜中）

• test-assert-cmd - 統合テストには assert_cmd を使用します
• test-predicates - 柔軟なアサーションには predicates を使用します
• test-temp-files - 一時テストファイルには assert_fs を使用します
• test-parse-from - パーサーのユニットテストには parse_from を使用します
• test-trycmd-snapshots - スナップショットテストには trycmd を使用します

使用方法

詳しい説明とコード例については、個々のリファレンスファイルをお読みください。

• セクションの定義 - カテゴリーの構成と影響レベル
• ルールのテンプレート - 新しいルールを追加するためのテンプレート

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルールのテンプレート
metadata.json	バージョンとリファレンス情報