@ riestools/cli- kit- yargs (英语)

用于可再使用的演员命令行应用程序的 Yargs 适配器.

包里没有雅格斯 @ariestools/cli-kit 而路由解析器帮助,版本,验证错误,同步失败,并通过核心退出 ProcessHost 边界。 这使得一个被配置的CLI安全地与录音主机一起锻炼,而不是让雅格斯写到环境控制台或终止测试过程.

帮助,版本,和完成输出 仍然结束运行的方式 Yargs自己的进程退出。 通过主机行走意味着Yargs不再结束过程;它记录出口并持续进行. 所以一旦Yargs离开0, runYargsApplication 跳过在解析器上注册的每一个中间软件,包括 .check() 召回电话。 一个根 --help, (中文(简体) ), -h,或裸体 help 因此,从未到达应用程序的配置中间软件,以及 app bogus --help 打印帮助而不是 Unknown command: bogus。根帮助也等待动脉 $0 构建者:亚格斯打印,只有在构建者和解后才会有所帮助,否则就是在解剖完成后. 未知命令失败在保留使用输出和失败映射的同时, 停止后期的中间件和匹配的处理器; 见 拒绝未知命令。 。 。 .

runYargsApplication 接受可选选项 mapFailureToExitCode 映射器既适用于解析器也适用于处理器故障:映射器收到故障源('parse' 对于验证失败, 'handler' 用于处理器或中间软件拒绝,返回一个数字,选择退出代码, undefined 保留默认退出代码一。 投出,或返回整数范围0–255以外的代码的映射器会倒回退出代码一. 故意行为 ProcessExitError 出口通过无动于衷.

根帮助使用 Yargs 的承诺返回 getHelp() 它的回调输出 路径。 拒绝同步 $0 建构者通过现有的 处理器- 失败边界: 没有成功帮助输出或命令效果, 1 onFailure 调用,原始错误会传递给映射器。 成功 帮助仍然等待建设者,未使用的默认建设者仍然懒惰. 两个中间软件阶段都等待等待帮助,然后决定是否运行. 明确字符串/ 默认 showHelp 超载保留了本地的Yargs行为.

失败的输出范围是同一来源。 A 类 剖析来源 失败( Yargs 验证或使用错误,包括由 rejectUnknownCommands)仍然打印用法/帮助块,因为呼叫者错误地输入了CLI. A 类 处理器来源 失败( 丢弃的命令处理器或中间软件—— 例如映射出一个退出的配置错误) 78将原始错误打印为 stderr, 包括它的堆栈当存在时, 没有用法堆放 。 生产保持了完整的诊断,因此致命的处理器故障仍然可以诊断;只有吵闹的用法被压制. 退出代码和 mapFailureToExitCode 合同不变;只有原产地的印刷品不同.

重复选项

configureCliSurface 对每个消费者实行一种重复政策 withRepeatableOptions(parser) 对组装的解析器适用同样的政策:

• 已声明选项 array: true 编号 : type: 'array' 收集每起事件(--tag a --tag b 给 ['a', 'b']),并具有可变位置(serve [files..]保持每个值;
• 已声明选项 nargs: n 与 n > 1 保留最后的 n 数值;
• 每一个其他宣布的选项都会在其所有拼写下解决最后的胜负——别名,骆驼Case和连字符键,点键——所以 --out a --out b 手握处理器 'b' 而不是数组.

保险单保留了 Yargs 的默认 duplicate-arguments-array: true 并恢复在验证前的中间软件中的最后胜利,所以 choices, (中文(简体) ), .check(...), (中文(简体) ), coerce,处理器只看到存活值: --mode bogus --mode safe 通过 choices: ['fast', 'safe'],以及 --mode safe --mode bogus 失败了。 转动 duplicate-arguments-array 关闭在 args 18 下不能替代 : 它只保留一个数组选项的最后一次出现, 将一个变量位置切换到其最后一个值, 并且可以留下一个数组选项的骆驼 大小写密钥不同意其连字符密钥.

import { runYargsApplication, withRepeatableOptions } from '@ariestools/cli-kit-yargs'

await runYargsApplication({
  host,
  configure: parser => withRepeatableOptions(parser.scriptName('app'))
    .command(serveCommand)
    .strictOptions()
    .help(),
})

三个制约因素使政策保持不变:

• 离开 duplicate-arguments-array 未设置于任意 .parserConfiguration(...) 电话,包括一个在a configureCliSurface customize 钩. 这个调用取代了 Yargs 的配置批发, 一个未设置的密钥保持了 Yargs 的默认 true· ; withRepeatableOptions 永远不要调用它,所以它不能丢弃之前应用的设置 .
• 应用 withRepeatableOptions 在宣布任何选项之前 coerce: yargs在注册顺序中作为中间软件运行强制函数,所以一个注册较早的收到未被拼接的数组.
• 宣布一个变相立场 .positional(...),将其记录为数组选项(.strictOptions() 拒绝未申报的立场。 仅通过命名 .coerce(...) 或非阵型 .option(...) 声明一个单值选项,其值崩溃到最后一个值.

拒绝未知命令

.strictCommands() 无法标记未知的命令一次 $0 默认命令是注册的——默认命令作为位置消耗出出错的符号,雅格斯默默接受. rejectUnknownCommands(parser, commands) 以 .check() 比较每个剩余位置与命令名称(和别名) commands,扔出一个解析来源 Unknown command: <token> 任何未确认的东西 赤裸裸的引用, 注册命令及其选项 help编号 :$0 路径没有变化。 在每个之后应用 .command(...) 登记和登记前 .help(),通过您注册的相同数组:

import { rejectUnknownCommands, runYargsApplication } from '@ariestools/cli-kit-yargs'

await runYargsApplication({
  host,
  mapFailureToExitCode: (_error, origin) => (origin === 'parse' ? 64 : undefined),
  configure: (parser) => {
    let configured = parser.scriptName('app')
    for (const command of commands) configured = configured.command(command)
    return rejectUnknownCommands(configured, commands).help().version(version)
  },
})

无论运行时间类型如何,检查所有非空的剩余标志。 弧线类型 argv._ 作为 (string | number)[] 并且,由于默认 parse-positional-numbers 启用后,就强制给联署材料号码一个赤裸的数字符号 app 0, (中文(简体) ), app 123,以及 app -5 标记为 Unknown command: 0 (等)一一如来相. 没有 .parserConfiguration({ 'parse-positional-numbers': false }) 需要绕道去抓一个数字迷路的人。 信息重复了被胁迫的价值,而不是原始文本,所以一个异国情调的字面规范化了—— 1e3 读取 Unknown command: 1000, (中文(简体) ), 0x10 读取 16, (中文(简体) ), 1.50 读取 1.5 因为Yargs已经胁迫了我们 .check() 运行。 拒绝在每一种情况下都是正确的;只有重复的文本不同。 空符号( A)app "")是排除的一条:它没有命令的名称,而掉到 $0。 。 。 .

四个制约因素使检查准确无误.

• 这个 commands 数组必须等同在解析器上注册的集——被接受的名称集是从中衍生出来的,而不是从解析器上读回,所以任何漂移都无声地拒绝一个有效的命令或接受一个未处理的命令.
• 每个被接受的位置必须在其命令字符串中宣布(serve <file>, (中文(简体) ), serve [file], (中文(简体) ), serve [files..]: Yargs 消耗已申报位置 argv._ 在检查运行前输入已命名的密钥——包括数值值的密钥,所以 serve <port> 引用为 serve 8080 但是,如果命令读取了它从未宣布过的临时性位置,那么它们就会留在 argv._ 将第一个被拒绝者视为 Unknown command: <value>。 。 。 .
• 在父命令中注册的子命令 builder 也必须出现在 commands雅格士留下两个符号 argv._ (单位:千美元)db migrate 产量 ['db', 'migrate']),因此,在数组中缺失的嵌入式名称被拒绝为 Unknown command: migrate。将嵌入式模块与顶层模块一起通过,以一个被接受的平面名称集为代价,确定:然后在顶层也接受嵌入式名称,从顶端到顶端 $0。 。 。 .
• 后键 -- 分隔符不会通过, 除非呼叫器允许 .parserConfiguration({ 'populate--': true })叶子叶 populate-- 默认关闭, 将这些符号合并为 argv._ 而不是说 argv['--']这样 app local -- raw 以 Unknown command: raw (和 app local -- 5 作为 Unknown command: 5) (中文(简体) ). 启用 populate-- 引导他们到 argv['--']页:1 argv._ 和这个检查的伸手.

当使用通过 runYargsApplication,一个未知的键盘检查稍后停止 中间软件和匹配的处理器:既不是 $0 赤裸的流浪者管理者 也没有 publish 处理器 app publish 0 执行。 用法输出, 剖析出源映射,默认出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出 保持原状 在拒绝检查前运行的中间软件和构建器 保留现有的执行命令。 这项担保属于适配器; 使用独立的 Yargs 解析调用程序必须提供等效 失败 - 退出行为本身。 上面的平面接受姓名限制 保持不变.

使用 environmentToYargsConfig 当应用程序拥有配置文件加载并想要替换 Yargs 进程时 - global .env() 以明确提供的环境进行检索。 由此而来平平的被点对象维护了雅格斯环境的关键正常化,并可以传递到 .config() 解析前 :

import { createNodeProcessHostWithDotEnv } from '@ariestools/cli-kit-node'
import { environmentToYargsConfig, runYargsApplication } from '@ariestools/cli-kit-yargs'

const host = createNodeProcessHostWithDotEnv()

await runYargsApplication({
  host,
  configure: parser => parser
    .option('port', { type: 'number' })
    .config(environmentToYargsConfig(host.environment, 'XL1', { allowedKeys: ['port'] }))
    .scriptName('xl1')
    .command(commands)
    .strictOptions()
    .help()
    .version(version),
})

装入 dotenv 文件通过 @ariestools/cli-kit-node (单位:千美元)loadDotEnvFile 编号 : createNodeProcessHostWithDotEnv)所以数值达到 host.environment 不发生变异 process.env。这种转换保留了命令线上环境优先级,但它不是Yargs-native配置文件选项的一般替代: Yargs 将配置对象排在配置文件下方, 并处理顶级 extends 键。 此类申请应先解决这些优先和保留关键规则,然后将标的送交 .config()。 。 。 .

使用严格的选项,保持环境许可清单的明确性,并在其名称中标明 映射形式( e)port, (中文(简体) ), rpcUrl) (中文(简体) ). 实例声明 port 全球,所以 配置对每个命令都是有效的 。 当命令接受不同的选项时, 声明选项和呼叫 configureCommandEnvironment 在每个选中的内 叶相生者. 帮助此边界需要允许列表; 独立 转换器保留其可选许可列表。 A 类 serve 构建者可以允许 port 时 (单位:千美元) status 允许构建器 format数字 :

import { configureCommandEnvironment, configureCliSurface, runYargsApplication } from '@ariestools/cli-kit-yargs'

const commandEnvironment = { environment: host.environment, prefix: 'APP_' }
const commands = [
  {
    command: ['serve', 'run'],
    builder: parser => configureCommandEnvironment(
      parser.option('port', { alias: 'p', type: 'number' }),
      { ...commandEnvironment, allowedKeys: ['port'] },
    ),
    handler: argv => serve(argv.port),
  },
  {
    command: 'status',
    builder: parser => configureCommandEnvironment(
      parser.option('format', { choices: ['json', 'text'], type: 'string' }),
      { ...commandEnvironment, allowedKeys: ['format'] },
    ),
    handler: argv => status(argv.format),
  },
]

await runYargsApplication({
  host,
  configure: parser => configureCliSurface(parser, {
    commands, host, scriptName: 'app', usage: 'app <command>', version,
  }),
})

APP_PORT=8080 APP_FORMAT=json app serve 只接收 port· ; app status 只接收 format。 。 。 . app run -p 9090 覆盖 APP_PORT,以及 app serve --format json 仍然失败 。 包含共享 当叶子接受它们时,每片叶子的允许列表中的全局键。 为了筑巢 命令,在叶子建构器内应用此助手,而不是父的 构建者:父配置对象由每个孩子继承.

无关联的前缀变量和其他命令的密钥被过滤. 保持打错的 CLI 旗帜严格. root-parser 选项无法导出反演 这个浮出水面,在懒惰的建设者运行之前。 过滤删除不支持 环境值; 仅使用配置字段的应用程序需要一个单独的 配置管道或明确宣布的选项。 通用转换器保存 其针对有意接受所有钥匙的消费者的可选许可列表。 现有 configureCliSurface.environmentConfig 仍然是根/全球配置路径 不推断或过滤特定命令的密钥。 它的召唤者只能保留 全球公布的密钥。 帮助者不会更改 Yargs 配置文件优先级 或对保留最高层的特殊解释 extends 键.

Mapped dotted keys保留了Yargs自己的严格验证规则. 随着它的默认 标记, 只声明 api.port 仍然产生一个 api 集装箱 严格选项可以拒绝为未知。 平平点选项表面可以使用 .parserConfiguration({ 'dot-notation': false }) 并宣布 api.port 当然 将任意嵌入的应用程序配置保留在单独的区域 配置管道,而不是把它当作CLI选项的联盟.

许可证

LGPL-3.0 仅限