blear.node.cli

1Introduction
2Example
3Static
4Dependencies
5Reference

1Introduction

description：node 命令行
author：ydr.me
create：2016年06月04日14:09:36
update：2018年08月16日10:18:27
github：https://github.com/blearjs/blear.node.cli

cli 定义的命令结构如下：

cli 是命令声明式语法，通常以 command 作为起点，后续的声明都是针对这个 command 进行的配置。

2Example

var cli = require('blear.node.cli');

cli
    .command()
    .helper()
    .versioing()

    .command('get')
    .useage('get <url>', '从远程获取资源')
    .option('username', {
        alias: 'u'
    })
    .option('password', {
        alias: ['p', 'P']
    })
    .action(fn)
    .parse();

3Static

3.1`.banner(banner): cli`

设置 banner 在执行每次 action 的时候都会输出。比如可以设置命令的 slogan 或者一个 ASCII 图像。

3.1.1`banner`

类型：string
说明：banner

3.2`.command(): cli`

设置根级命令描述，比如支持版本输出、帮助输出、用法等。

3.3`.command(command): cli`

设置命令描述，比如支持帮助输出、用法、参数、方法、动作等。

3.3.1`command`

类型：string
说明：命令

3.4`.versioning(): cli`

是否配置版本输出帮助。相当于

cli.option('version', {
    alias: ['v', 'V'],
    action: cli.version,
    description: 'balabala'
});

3.5`.helper(): cli`

是帮助信息输出帮助。相当于

cli.option('help', {
    alias: ['h', 'H'],
    action: cli.help,
    description: 'balabala'
});

3.6`.usage(example, [description]): cli`

配置命令用法。

3.6.1`example`

类型：string
说明：例子

3.6.2`description`

类型：string
说明：描述
默认：空

3.7`.option(key, [option]): cli`

配置命令用法，可以紧跟 command 或 method。

3.7.1`key`

类型：string
说明：配置键名，在终端上会显示为 -（短横线）分隔的形式，如 showYourName 会显示为 show-your-name，但在获取 args 时会显示为驼峰形式

3.7.2`option`

类型：string | object
说明：对配置的描述
- 如果是字符串：则作为配置的 description
- 如果是对象：则作为配置的对象描述
默认：空

3.7.3`option.alias`

类型：string | array(string)
说明：设置别名，如果是多个别名用数组表示，别名可以是单个字符，也可以是多个字符，但不能在一个命令里重复
默认：空

3.7.4`option.type`

类型：string
说明：配置值类型，支持以下类型：
- string：字符串
- boolean：布尔值
- array：数组
默认：string

3.7.5`option.default`

类型：string
说明：配置值默认值，如果未指定值的话
默认：针对以下类型：
- string：""（空字符串）
- boolean：false
- array：[]（空数组）

3.7.6`option.transform(val1, args, params): val2`

类型：function
说明：配置值的转换
默认：空

3.7.6.1`val1`

类型：*
说明：当前配置的值

3.7.6.2`args`

类型：object
说明：当前配置

3.7.6.3`params`

类型：[]
说明：其他参数，通常索引值为 0 的值为 method

3.7.6.4`val2`

类型：*
说明：转换后配置的值

3.7.7`option.description`

类型：string
说明：描述
默认：空

3.7.8`option.required`

类型：boolean
说明：是否必填
默认：false

3.7.9`option.message`

类型：string
说明：该配置键缺省时显示的消息
默认："balabala"

3.8`.action(action): cli`

创建一个动作，可以紧跟 command 或 method。

3.8.1`action(args, params)`

类型：function
说明：动作函数

3.8.1.1`args`

类型：object
说明：配置

3.8.1.2`params`

类型：array
说明：其他参数，通常索引值为 0 的值为 method

3.9`.error(error): cli`

自定义错误控制。紧跟 command。

3.9.1`error(key, args, option, params)`

类型：function
说明：捕获错误的函数，通常是参数为空的错误

3.9.1.1`key`

类型：string
说明：配置键名

3.9.1.2`args`

类型：object
说明：配置键值对

3.9.1.3`option`

类型：object
说明：配置对象描述

3.9.1.4`params`

类型：array
说明：其他参数，通常索引值为 0 的值为 method

3.10`.parse(options): undefined`

以当前执行的命令行参数进行解析。

3.10.1`options`

类型：object
说明：配置

3.10.2`options.registry`

类型：string
说明：版本检查的仓库
默认："http://registry.npm.taobao.org/"

3.10.3`options.breakLength`

类型：number
说明：键单行显示的长度，超过的话值会顺延换行
默认：30

3.10.4`options.bin`

类型：number
说明：命令名称
默认：自动获取，以 path.basename(process.argv[1]) 作为命令

3.10.5`options.package`

类型：object
说明：命令包描述，npmjs.com 官方文档

3.10.6`options.package.version`

类型：string
说明：命令包的本地版本

3.11`.parse(argv, options)`

指定执行的命令行参数进行解析。

3.11.1`argv`

类型：Array
说明：该参数来自 process.argv，nodejs.cn 非官方文档。

3.11.2`options`

同上。

3.12`.help(command, [params]): undefined`

打印帮助信息，可以按根命令打印：

3.12.1`command`

类型：String
说明：命令，根命令传空字符串

3.12.2`params`

类型：array
说明：其他参数，通常索引值为 0 的值为 method
默认：[]

cli.help('');

或子命令：

cli.help('domain');

3.13`.version(): undefined`

打印本地版本信息，并与 registry 里 dist-tags.latest 的版本进行比较，如果落后则打印版本升级提示。

3.14`.exec(command, [args], [params]): undefined`

执行命令。

3.14.1`command`

类型：String
说明：命令，根命令传空字符串

3.14.2`args`

类型：object
说明：配置对象描述
默认：{}

3.14.3`params`

类型：array
说明：其他参数，通常索引值为 0 的值为 method
默认：[]

3.15`.guess(guesser): cli`

未匹配命令的猜想。

3.15.1`guesser`

类型：function
说明：猜想函数

cli.guess(function (command, args, params) {
    console.log('你当前输入的命令是', command);

    if (/hep/.test(command)) {
        cli.help();
    } else {
        cli.exec('go', args, params);
    }
});

3.15.2`guesser(command, args, params): undefined`

3.15.2.1`command`

类型：String
说明：命令，根命令传空字符串

3.15.2.2`args`

类型：object
说明：配置对象描述
默认：{}

3.15.2.3`params`

类型：array
说明：其他参数，通常索引值为 0 的值为 method
默认：[]