Arg

arg 是一个无偏见、简洁的命令行参数解析器。

安装

npm install arg

使用方法

arg() 接受 1 或 2 个参数：

1. 命令行规范对象（见下文）
2. 解析选项（可选，默认为 {permissive: false, argv: process.argv.slice(2), stopAtPositional: false}）

它返回一个包含命令行上存在的任何值的对象（缺少的选项因此不会出现在结果对象中）。Arg 不执行任何验证/要求检查 - 我们将其留给应用程序。

所有未被选项消耗的参数（通常称为"额外"参数）都会被添加到 result._ 中，它始终是一个数组（即使没有传递额外参数，也会返回一个空数组）。

const arg = require('arg');

// `options` 是一个可选参数
const args = arg(
    spec,
    (options = { permissive: false, argv: process.argv.slice(2) })
);

例如：

$ node ./hello.js --verbose -vvv --port=1234 -n 'My name' foo bar --tag qux --tag=qix -- --foobar

// hello.js
const arg = require('arg');

const args = arg({
    // 类型
    '--help': Boolean,
    '--version': Boolean,
    '--verbose': arg.COUNT, // 计算 --verbose 被传递的次数
    '--port': Number, // --port <number> 或 --port=<number>
    '--name': String, // --name <string> 或 --name=<string>
    '--tag': [String], // --tag <string> 或 --tag=<string>

    // 别名
    '-v': '--verbose',
    '-n': '--name', // -n <string>; 结果存储在 --name 中
    '--label': '--name' // --label <string> 或 --label=<string>;
    //     结果存储在 --name 中
});

console.log(args);
/*
{
    _: ["foo", "bar", "--foobar"],
    '--port': 1234,
    '--verbose': 4,
    '--name': "My name",
    '--tag': ["qux", "qix"]
}
*/

每个键值对的值要么是类型（函数或 [函数]），要么是字符串（表示别名）。

• 如果是函数，参数值的字符串会被传递给它，返回值将作为最终值使用。

• 如果是数组，唯一的元素必须是类型函数。数组类型表示该参数可以多次传递，因此返回对象中的结果值是一个包含使用指定标志传递的所有值的数组。

• 如果是字符串，则建立一个别名。如果传递的标志与键匹配，则用值替换它。

类型函数接收三个参数：

1. 参数值（始终为字符串）
2. 参数名（例如 --label）
3. 目标的先前值（对于类似 reduce 的操作或支持多次 -v 等情况很有用）

这意味着内置的 String、Number 和 Boolean 类型构造函数可以"直接使用"作为类型函数。

注意，Boolean 和 [Boolean] 有特殊处理 - 不会消耗或传递选项参数，而是返回 true。这些选项被称为"标志"。

对于希望表现为标志的自定义处理程序，你可以通过 arg.flag() 传递函数：

const arg = require('arg');

const argv = [
    '--foo',
    'bar',
    '-ff',
    'baz',
    '--foo',
    '--foo',
    'qux',
    '-fff',
    'qix'
];

function myHandler(value, argName, previousValue) {
    /* `value` 始终为 `true` */
    return 'na ' + (previousValue || 'batman!');
}

const args = arg(
    {
        '--foo': arg.flag(myHandler),
        '-f': '--foo'
    },
    {
        argv
    }
);

console.log(args);
/*
{
    _: ['bar', 'baz', 'qux', 'qix'],
    '--foo': 'na na na na na na na na batman!'
}
*/

此外，arg 提供了一个名为 arg.COUNT 的辅助参数处理程序，它等同于 [Boolean] 参数的 .length 属性 - 有效地计算键所表示的布尔标志在命令行上被传递的次数。例如，这就是你如何实现 ssh 的多级详细程度（-vvvv 是最详细的）。

const arg = require('arg');

const argv = ['-AAAA', '-BBBB'];

const args = arg(
    {
        '-A': arg.COUNT,
        '-B': [Boolean]
    },
    {
        argv
    }
);

console.log(args);
/*
{
    _: [],
    '-A': 4,
    '-B': [true, true, true, true]
}
*/

选项

如果指定了第二个参数并且是一个对象，它会指定解析选项来修改 arg() 的行为。

argv

如果你已经切片或生成了一些要解析的原始参数（而不是让 arg 从 process.argv 中切片），你可以在 argv 选项中指定它们。

例如：

const args = arg(
    {
        '--foo': String
    },
    {
        argv: ['hello', '--foo', 'world']
    }
);

结果为：

const args = {
    _: ['hello'],
    '--foo': 'world'
};

permissive

当 permissive 设置为 true 时，arg 会将任何未知参数推送到"额外"参数数组（result._）中，而不是抛出关于未知标志的错误。

例如：

const arg = require('arg');

const argv = [
    '--foo',
    'hello',
    '--qux',
    'qix',
    '--bar',
    '12345',
    'hello again'
];

const args = arg(
    {
        '--foo': String,
        '--bar': Number
    },
    {
        argv,
        permissive: true
    }
);

结果为：

const args = {
    _: ['--qux', 'qix', 'hello again'],
    '--foo': 'hello',
    '--bar': 12345
};

stopAtPositional

当 stopAtPositional 设置为 true 时，arg 将在遇到第一个位置参数时停止解析。

例如：

const arg = require('arg');

const argv = ['--foo', 'hello', '--bar'];

const args = arg(
    {
        '--foo': Boolean,
        '--bar': Boolean
    },
    {
        argv,
        stopAtPositional: true
    }
);

结果为：

const args = {
    _: ['hello', '--bar'],
    '--foo': true
};

错误

arg 抛出的一些错误提供了 .code 属性，以帮助从用户错误中恢复，或区分用户错误和开发者错误（bug）。

ARG_UNKNOWN_OPTION

如果传递了一个未知选项（未在规范对象中定义），将抛出一个代码为 ARG_UNKNOWN_OPTION 的错误：

// cli.js
try {
    require('arg')({ '--hi': String });
} catch (err) {
    if (err.code === 'ARG_UNKNOWN_OPTION') {
        console.log(err.message);
    } else {
        throw err;
    }
}

node cli.js --extraneous true
Unknown or unexpected option: --extraneous

常见问题

以下是一些常见的问题和答案：

如何使用 arg 要求一个参数？

自己进行断言，例如：

const args = arg({ '--name': String });

if (!args['--name']) throw new Error('missing required argument: --name');

许可证

根据 MIT 许可证 发布。