引数 API

CLI 引数のスキーマ定義と解析ヘルパーは ptool.args と p.args にあります。

ptool.args.arg

v0.1.0 - Introduced.

ptool.args.arg(id, kind, options) は、 ptool.args.parse(...).schema.args で使う引数ビルダーを作成します。

id (string, 必須): 引数識別子。返されるテーブルでもキーになります。
kind (string, 必須): 引数タイプ。サポートされる値:
- "flag": 真偽値フラグ。
- "string": 文字列オプション。
- "int": 整数オプション (i64)。
- "positional": 位置引数。
options (table, 任意): ptool.args.parse の引数テーブルで使える long, short, help, required, multiple, default などの同じ任意フィールド。

このビルダーはメソッドチェーンをサポートしており、すべて自身を返します:

arg:long(value) は長いオプション名を設定します。positional 以外の引数でのみサポートされます。
arg:short(value) は短いオプション名を設定します。positional 以外の引数でのみサポートされます。
arg:help(value) はヘルプテキストを設定します。
arg:required(value) はその引数が必須かどうかを設定します。value を省略した場合のデフォルトは true です。
arg:multiple(value) はその引数を繰り返し指定できるかどうかを設定します。 value を省略した場合のデフォルトは true です。
arg:default(value) はデフォルト値を設定します。value = nil の場合はデフォルト値がクリアされます。

例:

local res = ptool.args.parse({
  args = {
    ptool.args.arg("name", "string"):required(),
    ptool.args.arg("verbose", "flag", { short = "v" }),
    ptool.args.arg("paths", "positional"):multiple(),
  }
})

ptool.args.parse

v0.1.0 - Introduced.

v0.3.0 - Added subcommands support.

ptool.args.parse(schema) は clap を使ってスクリプト引数を解析し、 id をキーとするテーブルを返します。

スクリプト引数は ptool run <lua_file> -- ... の -- 以降から取得されます。

たとえば:

ptool.use("v0.1.0")

local res = ptool.args.parse({
    name = "test",
    about = "The test command",
    args = {
        { id = "name", kind = "string" }
    }
})

print("Hello, " .. res.name .. "!")

スキーマ構造

name (string, 任意): ヘルプ出力に使われるコマンド名。デフォルトはスクリプトファイル名です。
about (string, 任意): ヘルプ説明。
args (table, 任意): 引数定義の配列。各要素は次の 2 形式をサポートします:
- 引数テーブル。
- ptool.args.arg(...) が返すビルダーオブジェクト。
subcommands (table, 任意): サブコマンド名からサブコマンドスキーマへのマップ。各サブコマンドスキーマは about, args, subcommands を再帰的にサポートします。

args または subcommands の少なくともどちらか一方は指定する必要があります。

引数テーブルのフィールド:

id (string, 必須): 引数識別子。返されるテーブルでもキーになります。
kind (string, 必須): 引数タイプ。サポートされる値:
- "flag": 真偽値フラグ。
- "string": 文字列オプション。
- "int": 整数オプション (i64)。
- "positional": 位置引数。
long (string, 任意): "name" のような長いオプション名 (--name) です。positional 以外の引数では、デフォルト値を id から導出できます。
short (string, 任意): -v の "v" のような 1 文字の短いオプション名。
help (string, 任意): 引数のヘルプテキスト。
required (boolean, 任意): その引数が必須かどうか。デフォルトは false。
multiple (boolean, 任意): その引数を繰り返し指定できるかどうか。デフォルトは false。
default (string/integer, 任意): デフォルト値。

subcommands が存在する場合、現在のコマンドの args はそのコマンドツリー全体で共有されるオプションとして扱われ、選択したサブコマンドの前後どちらでも受け付けられます。

サブコマンド付きの例:

local res = ptool.args.parse({
  name = "demo",
  args = {
    ptool.args.arg("verbose", "flag", { short = "v" }),
    ptool.args.arg("config", "string"),
  },
  subcommands = {
    build = {
      args = {
        ptool.args.arg("release", "flag"),
      },
      subcommands = {
        web = {
          args = {
            ptool.args.arg("out", "string"):required(),
          },
        },
      },
    },
    clean = {
      args = {
        ptool.args.arg("all", "flag"),
      },
    },
  },
})

制約

以下の制約は、引数テーブルとビルダー構文の両方に適用されます。
positional 以外の引数では long と short を省略できます。 long を省略すると id が自動で使われます。
positional 引数では long, short, default を設定できません。
positional.multiple = true の場合、その引数は args の最後である必要があります。
multiple = true は string と positional でのみサポートされます。
default は string と int でのみサポートされ、multiple = true と同時には使えません。
subcommands が存在する場合、その同じスキーマ内では positional 引数は許可されません。
トップレベルに subcommands がある場合、引数 id command_path と args は予約済みです。
ひとつの選択されたサブコマンドパス上では、祖先と子孫のサブコマンドが同じ引数 id を再利用することはできません。値が 1 つの args テーブルにマージされるためです。

戻り値

Lua テーブルが返され、キーは id、値型は次のとおりです:

flag -> boolean
string -> string (multiple = true の場合は string[])
int -> integer
positional -> string (multiple = true の場合は string[])

subcommands が存在しない場合、戻り値は上記のようなフラットな形のままです。

subcommands が存在する場合、戻り値は次の形になります:

トップレベル args の値は、トップレベルテーブル上にそのまま返されます。
command_path -> string[]: 一致したサブコマンドパス。たとえば {"build", "web"}。
args -> table: 一致したサブコマンドパスからマージされた引数値。

たとえば:

{
  verbose = true,
  config = "cfg.toml",
  command_path = { "build", "web" },
  args = {
    release = true,
    out = "dist",
  },
}

ptool.args.arg​

ptool.args.parse​

スキーマ構造​

制約​

戻り値​

ptool.args.arg

ptool.args.parse

スキーマ構造

制約

戻り値