@davidwells/dx-args (英语)

用于 CLIs 的原谅 argv 解析器, 当有人输入一个稍有不完美的命令时, 它应该继续工作 .

@davidwells/dx-args 保留 oparser 作为值解析器。 它增加了argv常态,文件/glob分组,单盘长选项恢复,以及周围的可预见结果形状.

const { dxParse } = require('@davidwells/dx-args')

const result = dxParse(['-files', 'README.md', '-dry'])

console.log(result.mergedOptions)
// { files: 'README.md', dry: true }

console.log(result.globGroups)
// [{ key: 'files', rawKey: '-files', values: ['README.md'] }]

安装

npm install @davidwells/dx-args

API 密码

const {
  dxParse,
  getGlobGroupsFromArgs,
  splitOutsideQuotes,
} = require('@davidwells/dx-args')

dxParse(argv, opts)

解析一个 argv 数组并返回 a ParseResult。 。 。 .

const result = dxParse(['--stage', 'prod', 'cool', '=', 'true'])

console.log(result.mergedOptions)
// { stage: 'prod', cool: true }

getGlobGroupsFromArgs(argv, opts)

将文件和类似 glob 的值提取到分组集合中 .

const result = getGlobGroupsFromArgs(
  ['--files', 'README.md', 'docs/**/*.md'],
  { globKeys: ['files'] }
)

console.log(result.globGroups)
// [{ key: 'files', rawKey: '--files', values: ['README.md', 'docs/**/*.md'] }]

splitOutsideQuotes(input)

在保存引用的字符串、对象、阵列和 key = value 表单.

splitOutsideQuotes('name = "David Wells" config={ enabled: true }')
// ['name="David Wells"', 'config={ enabled: true }']

接受输入表

文件及类似光彩的值也会通过 globGroups。 。 。 .

const result = dxParse(['README.md', 'docs/**/*.md', '--stage', 'dev'])

console.log(result.globGroups)
// [{ key: '', rawKey: '', values: ['README.md', 'docs/**/*.md'] }]

console.log(result.mergedOptions)
// { stage: 'dev' }

结果形状

interface GlobGroup {
  key: string
  rawKey: string
  values: Array<string | RegExp>
}

interface ParseResult {
  rawArgv: string
  leadingCommands: string[]
  globGroups: GlobGroup[]
  extraParse: Record<string, unknown>
  mriOptionsOriginal: Record<string, unknown>
  mriOptionsClean: Record<string, unknown>
  mriDiff: boolean
  yargsParsed: string
  mergedOptions: Record<string, unknown>
}

大多数打电话者应使用:

• mergedOptions 用于解析选项.
• globGroups 用于文件和光泽工作流程.
• leadingCommands 当一个 CLI 在选项前有类似命令的主词时 .

其余领域是诊断:

• extraParse 这是 oparser- 阿尔格夫正常化后得出的分析结果.
• mriOptionsOriginal 原生为 mri 结果.
• mriOptionsClean 实值 mri 在清理了诸如来自 -stage。 。 。 .
• mriDiff 当清理更改时是真实的 mri 结果.
• yargsParsed 不活动;它目前是一个兼容/调试字段.

球组

@davidwells/dx-args 组文件外观和光滑外观参数,这样CLIs就可以从普通选项中分别处理文件.

dxParse(['--files', 'README.md', 'docs/**/*.md']).globGroups
// [{ key: 'files', rawKey: '--files', values: ['README.md', 'docs/**/*.md'] }]

空白文件和 glob 值使用空密钥 :

dxParse(['README.md', 'docs/**/*.md']).globGroups
// [{ key: '', rawKey: '', values: ['README.md', 'docs/**/*.md'] }]

自定义 glob 密钥可配置 :

dxParse(['--ignore', 'dist/**/*.md'], {
  globKeys: ['files', 'file', 'path', 'ignore']
}).globGroups
// [{ key: 'ignore', rawKey: '--ignore', values: ['dist/**/*.md'] }]

贝壳扩展的文件列表被故意不作为主命令处理:

const result = dxParse(['README.md', 'NOTES.md', 'build', '=', 'false'])

console.log(result.globGroups)
// [{ key: '', rawKey: '', values: ['README.md', 'NOTES.md'] }]

console.log(result.mergedOptions)
// { build: false }

包含的值 node_modules/ 正在从 glob 组过滤.

复制值

重复的旗帜默认是最后的- write- wins .

dxParse(['--stage', 'dev', '--stage', 'prod']).mergedOptions
// { stage: 'prod' }

累积是明确的:

dxParse(['--tag', 'one', '--tag', 'two'], {
  accumulate: ['tag']
}).mergedOptions
// { tag: ['one', 'two'] }

解析器目前接受三个累积选项名:

• accumulate
• accumulateFlags
• arrayKeys

偏爱 accumulate 在新代码.

单一 Dash 政策

多特征的单段选项被视为允许长段选项:

dxParse(['-stage', 'prod']).mergedOptions
// { stage: 'prod' }

当值看起来像文件时, 也起作用 :

dxParse(['-config', 'md.config.js']).mergedOptions
// { config: 'md.config.js' }

单独的短旗仍然工作 :

dxParse(['-l', '-a', '-h']).mergedOptions
// { l: true, a: true, h: true }

短组是选入的,因为它们与允许长时间恢复选项相冲突:

dxParse(['-abc']).mergedOptions
// { abc: true }

dxParse(['-abc'], {
  allowShortClusters: true,
  shortFlags: ['a', 'b', 'c']
}).mergedOptions
// { a: true, b: true, c: true }

标记下魔法集成

魔法用途 dxParse 作为它的CLI解析边界.

标记下魔法地图解析器输出如下 :

• file, (中文(简体) ), files, (中文(简体) ), path,则赤色文件组变为 config.files。 。 。 .
• ignore 组成为 config.ignore。 。 。 .
• 其它 mergedOptions 成为Markdown Magic Cconfig 覆盖.
• output 财务报告和审定财务报表 outputDir 正常化发生在Markdown Magic,不是 @davidwells/dx-args。 。 。 .

示例 Markdown 魔法命令 :

md-magic -files README.md -config md.config.js -dry
md-magic --path "docs/**/*.md" --ignore "dist/**/*.md"

调试

软件包包含一个打印完整剖析结果的 CLI :

dx-args -files README.md -config md.config.js -dry

调试时, 请检查:

• mergedOptions
• globGroups
• mriOptionsOriginal
• mriOptionsClean
• mriDiff

已知差距

• 以空格分隔列表抓取 --numbers 1 2 3 --strings a b c 尚未支持.
• 带有引号的真 shell argv 应该作为数组进行测试, 而不仅仅是字符串相接的固定装置 .
• 诊断领域可移入a debug 或者说 trace 在稳定之前的字段 1.0.0。 。 。 .
• node_modules/ 过滤器目前被构建为 glob 分组 .
• -- 休息通道应在作为公共API记录之前加以规定和测试.