选项

选项用于为命令提供额外的配置和参数。Clerc 支持多种类型的选项，包括 JavaScript 内置的类型，如布尔值、字符串、数字等，也支持自定义类型。

Clerc 的选项解析由 @clerc/parser 提供支持，并具有许多功能：

• 数组和自定义类型
• 选项分隔符：--flag value、--flag=value、--flag:value 和 --flag.value
• 组合别名：-abcd 2 → -a -b -c -d 2
• 选项结束符：传递 -- 来结束选项解析

可以在 flags 对象属性中指定选项，其中键是选项名称，值是选项类型函数或描述选项的对象。

建议使用驼峰命名法作为选项名称，因为它将被解释为解析短横线分隔的等效选项。

选项类型函数可以是任何接受字符串并返回解析后的值的函数。默认的 JavaScript 构造函数应该涵盖大多数用例：String、Number、Boolean 等。

选项描述对象可用于存储有关选项的其他信息，例如 short、default 和 description。要接受选项的多个值，请将类型函数包装在数组中。

所有提供的信息将用于生成更好的帮助文档。

选项短名称

选项短名称允许用户使用单个字符来指定选项。这对于为常用的选项提供便捷的快捷方式很有用。

定义短名称

你可以使用short属性为选项定义一个单字符的短名称：

const cli = Cli()
  .command("build", "构建项目", {
    flags: {
      output: {
        type: String,
        short: "o",
        description: "输出目录",
      },

      verbose: {
        type: Boolean,
        short: "v",
        description: "启用详细输出",
      },
    },
  })
  .on("build", (ctx) => {
    // $ node cli.mjs build --output dist
    // $ node cli.mjs build -o dist
    // 两者的工作方式相同
    // $ node cli.mjs build --verbose
    // $ node cli.mjs build -v
    // 两者都启用详细输出
  })
  .parse();

验证规则

• flag名称必须至少包含2个字符
• short属性必须恰好为1个字符

组合短名称

使用短名称（单个字符）时，它们可以组合在一起：

const cli = Cli()
  .command("compress", "压缩文件", {
    flags: {
      output: {
        type: String,
        short: "o",
        description: "输出文件",
      },

      verbose: {
        type: Boolean,
        short: "v",
        description: "详细输出",
      },

      recursive: {
        type: Boolean,
        short: "r",
        description: "递归模式",
      },
    },
  })
  .on("compress", (ctx) => {
    // $ node cli.mjs compress -vrh input.zip
    // 等同于：
    // $ node cli.mjs compress -v -r -h input.zip
    // 这设置了：verbose = true，recursive = true，并将 "input.zip" 作为参数传递
  })
  .parse();

标志描述

description 属性是可选的，如果你不需要记录标志，可以省略它：

const cli = Cli()
  .command("build", "构建项目", {
    flags: {
      verbose: {
        type: Boolean,
        // 描述是可选的
      },

      output: {
        type: String,
        description: "输出目录", // 或包含它以获得更好的文档
      },
    },
  })
  .parse();

必需的选项

要使选项成为必需的，可以在选项描述对象中将 required 属性设置为 true：

const cli = Cli()
  .command("deploy", "部署应用程序", {
    flags: {
      env: {
        type: String,
        description: "部署环境",
        required: true, // 这个选项是必需的
      },
    },
  })
  .on("deploy", (ctx) => {
    ctx.flags.env; // 这将始终有一个值
  })
  .parse();

默认值

你可以在选项描述对象中使用 default 属性为选项提供默认值：

const cli = Cli()
  .command("serve", "启动服务器", {
    flags: {
      port: {
        type: Number,
        description: "端口号",
        default: 3000, // 默认端口是 3000
      },
    },
  })
  .on("serve", (ctx) => {
    ctx.flags.port; // 如果未提供，则默认为 3000
  })
  .parse();

WARNING

如果一个标志被标记为 required 并且也有一个 default 值，那么在运行时会抛出一个 InvalidSchemaError，并且在类型检查期间会引发类型错误。

标志类型

关于标志类型的详细信息，包括内置基础类型（String、Boolean、Array、Counter、Object）和高级类型（Enum、Range、Regex），以及自定义类型定义，请参阅类型指南。