跳到主要内容

Args API

CLI 参数模式定义与解析辅助能力位于 ptool.args 和 p.args 下。

ptool.args.arg​

v0.1.0 - 引入。

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 - 引入。

v0.3.0 - 添加 subcommands 支持。

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 .. "!")

Schema 结构​

  • name（string，可选）：命令名称，用于帮助输出。默认是脚本文件名。
  • about（string，可选）：帮助描述。
  • args（table，可选）：参数定义数组。每个元素支持两种形式：
    • 参数表。
    • ptool.args.arg(...) 返回的构造器对象。
  • subcommands（table，可选）：子命令名到子命令 schema 的映射。每个子命令 schema 都支持递归定义 about、args 和 subcommands。

args 和 subcommands 至少要提供一个。

参数表字段：

  • id（string，必填）：参数标识符。它也会作为返回表中的键。
  • kind（string，必填）：参数类型。支持：
    • "flag"：布尔开关。
    • "string"：字符串选项。
    • "int"：整数选项（i64）。
    • "positional"：位置参数。
  • long（string，可选）：长选项名，例如 "name" 对应 --name。对于非 positional 参数，默认可以从 id 推导。
  • short（string，可选）：短选项名，单个字符，例如 "v" 对应 -v。
  • 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 时，同一层 schema 中不能定义 positional 参数。
  • 当顶层存在 subcommands 时，参数 id command_path 和 args 为保留名。
  • 在一条实际命中的子命令路径上，祖先和后代子命令不能复用同一个参数 id， 因为它们会被合并到同一个 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",
  },
}