Optionator

Optionator是一个JavaScript/Node.js选项解析和帮助生成库 eslint， 掌握， LiveScript， esmangle， escodegen, 更多的。

有关在线演示，请查看 掌握在线演示。

关于 · 用法 · 设置格式 · 参数格式

为什么?

其他选项解析器的问题，例如 yargs 或 minimist他们只是接受所有输入，不管有效与否。 使用Optionator，如果你输错了一个选项，它会给你一个错误（对你的意思有一个建议）。 如果您为某个选项提供了错误类型的参数，它将给您一个错误，而不是向您的应用程序提供错误的输入。

$ cmd --halp
Invalid option '--halp' - perhaps you meant '--help'?

$ cmd --count str
Invalid value for option 'count' - expected type Int, received value: str.

其他有用的功能包括根据控制台的大小重新格式化帮助文本，以便它适合即使控制台很窄，并接受不仅仅是一个数组(例如。的过程。Argv)，但也可以是字符串或对象，使测试之类的事情更容易。

关于

Optionator使用 类型检查 和 levn 在后台根据指定的类型投射和验证输入。

麻省理工学院的许可。版本0.9.4

npm install optionator

有关Optionator的更新，请 在twitter上关注我。

Optionator是一个Node.js模块，但如果打包了webpack/browserify，也可以在浏览器中使用。

用法

require('optionator'); 返回一个函数。它有一个性质， VERSION，以字符串形式表示库的当前版本。此函数使用指定选项和其他信息的对象调用，请参阅 设置格式部分． 这反过来返回一个具有三个属性的对象， parse， parseArgv， generateHelp, generateHelpForOption，都是函数。

var optionator = require('optionator')({
    prepend: 'Usage: cmd [options]',
    append: 'Version 1.0.0',
    options: [{
        option: 'help',
        alias: 'h',
        type: 'Boolean',
        description: 'displays help'
    }, {
        option: 'count',
        alias: 'c',
        type: 'Int',
        description: 'number of things',
        example: 'cmd --count 2'
    }]
});

var options = optionator.parseArgv(process.argv);
if (options.help) {
    console.log(optionator.generateHelp());
}
...

parseOptions解析(输入)

parse 处理 input 根据您的设置，并返回一个带有结果的对象。

参数

• 输入- [String] | Object | String -要解析的输入
• parseOptions - {slice: Int} -所有选项可选
  • slice 指定如果输入是数组或字符串（默认情况下），从开始切片的长度 0 对于字符串, 2 For数组(与 process.argv）

返回

Object -解析的选项，每个键是选项名称的驼峰大小写版本（用破折号指定），每个值是该选项的处理值。下的数组中包含位置值 _ 关键。

例子

parse(['node', 't.js', '--count', '2', 'positional']); // {count: 2, _: ['positional']}
parse('--count 2 positional');                         // {count: 2, _: ['positional']}
parse({count: 2, _:['positional']});                   // {count: 2, _: ['positional']}

parseArgv(输入)

parseArgv 工作原理完全一样 parse，但只针对数组输入，它会分割前两个元素。

参数

• 输入- [String] -要解析的输入

返回

参见“parse”中的“returns”部分

例子

parseArgv(process.argv);

generateHelp (helpOptions)

generateHelp 根据您的设置生成帮助文本。

参数

• helpOptions - {showHidden: Boolean, interpolate: Object} -所有选项可选
  • showHidden 指定是否显示选项 hidden: true 指定，默认为 false
  • interpolate 指定要插入的数据 prepend 和 append 文本, {{key}} 是格式-例如。 generateHelp({interpolate:{version: '0.4.2'}})我将改变这一点 append 文本: Version {{version}} 来 Version 0.4.2

返回

String -生成的帮助文本

例子

generateHelp(); /*
"Usage: cmd [options] positional

  -h, --help       displays help
  -c, --count Int  number of things

Version  1.0.0
"*/

generateHelpForOption (optionName)

generateHelpForOption 为指定的控件生成展开的帮助文本 optionName 选择。如果一个 example 为该选项指定，它将被显示，如果是 longDescription 时，它将显示该值而不是 description。

参数

• optionName - String -要显示的选项名称

返回

String -该选项生成的帮助文本

例子

generateHelpForOption('count'); /*
"-c, --count Int
description: number of things
example: cmd --count 2
"*/

设置格式

当你的 require('optionator')，你会得到一个函数，它接受一个设置对象。这个对象的类型是：

{
  prepend: String,
  append: String,
  options: [{heading: String} | {
    option: String,
    alias: [String] | String,
    type: String,
    enum: [String],
    default: String,
    restPositional: Boolean,
    required: Boolean,
    overrideRequired: Boolean,
    dependsOn: [String] | String,
    concatRepeatedArrays: Boolean | (Boolean, Object),
    mergeRepeatedObjects: Boolean,
    description: String,
    longDescription: String,
    example: [String] | String
  }],
  helpStyle: {
    aliasSeparator: String,
    typeSeparator: String,
    descriptionSeparator: String,
    initialIndent: Int,
    secondaryIndent: Int,
    maxPadFactor: Number
  },
  mutuallyExclusive: [[String | [String]]],
  concatRepeatedArrays: Boolean | (Boolean, Object), // deprecated, set in defaults object
  mergeRepeatedObjects: Boolean, // deprecated, set in defaults object
  positionalAnywhere: Boolean,
  typeAliases: Object,
  defaults: Object
}

所有属性都是可选的 Maybe （为了简单起见被排除在外），除了有任何一个 heading: String 或 option: String 中的每个对象 options 数组中。

顶级属性

• prepend 是否要在帮助文本中的选项之前放置一个可选字符串
• append 是否要在帮助文本中的选项之后放置一个可选字符串
• options 是否需要一个指定选项和标题的数组，选项和标题将按照指定的顺序显示
• helpStyle 是一个可选对象，使您能够更改帮助文本某些方面的默认外观
• mutuallyExclusive 是字符串数组或字符串数组的可选数组。顶层数组是一个规则列表，每个规则是一个元素列表——每个元素可以是一个字符串（一个选项的名称），也可以是一个字符串列表（一组选项名称）——如果存在多个元素，将会出现错误
• concatRepeatedArrays 参见“选项属性”标题下的描述-不建议在顶层使用，如果您想为所有选项设置此属性，请使用 defaults 财产
• mergeRepeatedObjects 参见“选项属性”标题下的描述-不建议在顶层使用，如果您想为所有选项设置此属性，请使用 defaults 财产
• positionalAnywhere 是一个可选的布尔值(默认为 true) -何时 true 它允许位置参数在任何时间 false，在第一个位置参数之后的所有参数也被视为位置参数，即使它们看起来像一个标志。例如， positionalAnywhere: false，论点 --flag --boom 12 --crack 将有两个位置参数： 12 和 --crack
• typeAliases 是一个可选对象，它允许您为类型设置别名，例如。 {Path: 'String'} 会允许你使用这种类型吗 Path 作为类型的别名 String
• defaults 是遵循选项属性格式的可选对象，它为所有选项指定默认值。如果手动设置，默认值将被覆盖。例如，你可以这样做 default: { type: "String" } 将所有选项的默认类型设置为 String，然后在单个选项中通过设置 type 财产

标题属性

• heading 必需的字符串，标题的名称

选择属性

• option 选项的必需名称——使用破折号，不带前导破折号
• alias 是一个可选的字符串或字符串数组，其中指定了该选项的任何别名
• type 中是否有必需的字符串 类型检查 格式，这将用于强制转换输入值并对其进行验证
• enum 是一个可选的字符串数组，每个字符串会被解析吗 levn -参数值必须是结果值之一-每个潜在值必须对指定的值进行验证 type
• default 是一个可选字符串，它将被解析 levn 如果没有设置，则用作默认值-该值必须针对指定的值进行验证 type
• restPositional 是否可选的布尔值- if设置为 true选项之后的所有内容都将被视为位置参数，即使它看起来像一个命名参数
• required 是否可选的布尔值- if设置为 true，如果未定义选项，则选项解析将失败
• overrideRequired 是否可选的布尔值- if设置为 true 这个选项被使用了，还有另一个选项是必需的，但没有设置，它会覆盖对必需选项的需要，并且不会出现错误——如果你有必需的选项并且想要使用，这是有用的 --help 或 --version 旗帜
• concatRepeatedArrays 是一个可选的布尔值或具有布尔值和选项的元组对象(默认为 false) -当设置为时 true 如果一个选项包含一个数组值并且重复，则该标志的后续值将被附加，而不是覆盖原始值。选项 g 类型的 [String]： -g a -g b -g c,d 会导致 ['a','b','c','d']

你可以通过给出以下值来提供一个options对象： [true, options]． 目前支持的选项是 oneValuePerFlag，这只允许每个标志一个数组值。如果潜在值包含逗号，这很有用。

• mergeRepeatedObjects 是一个可选的布尔值(默认为 false) -当设置为时 true 如果一个选项包含一个对象值并且被重复，则该标志的后续值将被合并，而不是覆盖原始值。选项 g 类型的 Object： -g a:1 -g b:2 -g c:3,d:4 会导致 {a: 1, b: 2, c: 3, d: 4}
• dependsOn 是一个可选的字符串或字符串数组-如果只是一个字符串（另一个选项的名称），它将确保设置其他选项，如果是字符串数组，取决于是否 'and' 或 'or' 首先，它将检查是否所有(['and', 'option-a', 'option-b'])，或至少一个(['or', 'option-a', 'option-b'])设置其他选项
• description 是一个可选字符串，它将显示在帮助文本中的选项旁边
• longDescription 是一个可选字符串，它将代替 description 当 generateHelpForOption 使用
• example 是一个可选的字符串或字符串数组，其中包含该选项的示例-这些将在何时显示 generateHelpForOption 使用

帮助样式属性

• aliasSeparator 是一个可选字符串，用于分隔多个名称-默认值：‘,’
• typeSeparator 是一个可选字符串，将类型与名称分开-默认值：‘ ’
• descriptionSeparator 是一个可选字符串，将描述与填充的名称和类型分开-默认值：‘ ’
• initialIndent 是可选的int -选项的缩进量-默认：2
• secondaryIndent 是否一个可选的int -如果完全包装缩进的量（除了初始缩进）-默认：4
• maxPadFactor 是一个可选的数字-影响名称/类型的默认填充级别，它乘以名称/类型长度的平均值-默认：1.5

参数格式

在最高级别上有两种类型的参数：命名参数和位置参数。

任何长度的名称参数都以 -- (如。 --go)，一个字符的前缀可以是 -- 或 - (如。 -g）.

有两种类型的命名参数：布尔标志(例如； --problemo， -p)，它不带值，结果是a true 如果它们存在，则假的 undefined 如果他们不在场，或者 false 如果出现并明确地以 no (如。 --no-problemo）. 带值的命名参数(例如。 --tseries 800， -t 800)是另一种类型。如果该选项具有类型 Boolean 它将自动变成一个布尔标志。任何其他类型都会产生一个带值的命名参数。

有关如何正确设置类型以获得所需值的更多信息，请参阅 类型检查 和 levn 页面。

您可以对使用单个 -但是，除了最后一个之外，其他都必须是布尔标志（不带值）。最后一个可以是布尔标志，也可以是带值的参数。 -ba 2 等于 -b -a 2。

位置参数是不属于上述范围的所有值-它们可以在任何地方，而不仅仅是在末尾。例如，在 cmd -b one -a 2 two 在 b 是布尔标志，和 a 有类型 Number有两个位置参数， one 和 two。

a之后的所有内容 -- 是位置参数，即使它看起来像一个命名参数。

您可以选择使用 = 将选项名与值分开，例如： --count=2。

如果您指定了选项 NUM，则使用单个参数的任何参数 - 后面跟着一个数字将是有效的，并将设置的值 NUM． 如。 -2 将被解析为 NUM: 2。

如果存在重复的命名参数，则取最后一个。

技术对

optionator 写在 LiveScript -一种编译成JavaScript的语言。它使用 levn 将参数强制转换为其指定类型，并使用 类型检查 验证值。它还使用 prelude.ls 图书馆。