@fxtop/commander

简易版Nodejs命令行交互工具，通过ORM(Object Relational Mapping)编程模式，简单快速地注册命令、参数、选项，以及相应的处理函数。

目录

1. 文档
   1. 安装
   2. 示例
   3. 类
   4. 方法
2. 支持
3. 版本特性
4. 问题
5. 许可证

目标和理念

@fxtop/commander 努力为Nodejs开发者提供一个简单快捷的命令行交互工具，通过类似 ORM 的方式快速定义 命令 、参数、 选项 ，以及它们的处理函数。在解析用户输入命令时，根据相应定义校验数据的正确性，并构造相应结果作为参数给该命令所绑定的处理函数。

Note: @fxtop/commander 提供的命令行交互功能，是基于 commander 封装的，如需进行更多底层操作，可以通过导入 @fxtop/commander 暴露的 Command类 实现。

documentation

installation

npm install @fxtop/commander

examples

Nodejs代码：

import semver from 'semver';
import Commander from '@fxtop/commander';

const commander = new Commander('test');

commander.registry(
    'check',
    { version: 'string' },
    {
      match: { type: 'string', oneof: ['^1.0.0', '^2.0.0'] },
    },
    (args, opts) => {
        const { version } = args;
        const { match } = opts;
        console.log('版本兼容：', semver.satisfies(version, match));
    }
);

commander.execute();

命令行输入：

# 指令  命令 <参数>  [选项]
  test check 1.2.3 -m ^1.0.0

classes

Commander

Commander为库的主要类，一个指令对应一个Commander实例。Commander实例化时接受两个参数，一个是指令的名称，另一个为指令对应的版本号。

Note: 指令名称参数并不能作为命令行实际输入的指令。

import Commander from '@fxtop/commander';

const commander = new Commander('test', '1.0.0');

Command

Command类与commander库中的Command类用法一致，可参考 commander 库。

import { Command } from '@fxtop/commander';

const newCommand = new Command().version('1.0.0');

methods

commander.registry(cmd, args, opts, handler) -> void

注册命令，并设置命令的 参数 选项 处理函数 等信息

• cmd (String): 注册命令，如过用户输入该命令，将会触发该命令中注册的处理函数handler

• args (Object): 为命令添加参数，并描述参数的类型和取值

• opts (Object): 为命令添加选线，并描述选项的类型和取值

• handler (Function): 注册命令的处理函数

Args & Opts

args 和 opts 都为对象类型参数，其 key 值即为相应的 参数 / 选项 的名称，且 参数 的位置即为定义对象key的先后顺序。其 value 可以为 String/Object 类型，当为String类型时，主要用于限制 参数 / 选项 的数据类型，如 'number', 'string', 'boolean'，当为对象时可以配置更多的限制信息。

Note1: 由于对象遍历顺序读取限制，尽量不要使用数字(number)作为对象的key值。
Note2: opts的key首字母小写为选项的简写，如果key值首字母相同，可以通过配置short避免简写重复

commander.registry(
    'check',
    /*--------- args 参数配置对象 ---------*/
    {
      /* 
      * value为 String 类型时，通过"|"分割符分割参数配置
      **  左边指定参数值的类型，默认为 string
      **  右边指定是否为可选参数，默认为 false
      */
      arg1: 'string | true',
      
      /* value为 Object 类型时 */
      arg2: {
        type: 'string',       // 参数值类型，默认为string
        optional: false,      // 参数是否必填，默认为false
        oneof: ['yes', 'no'], // 设置参数的取值范围，必须为数组中的某个值
      },
    },

    /*--------- 选项配置对象 ---------*/
    {
      /* 
      * value为 String 类型时，通过"|"分割符分割选项配置
      **  左边指定选项值的类型，默认为 string
      **  右边为选项值的描述，查看帮助时可以看到选项的描述
      */
      opt1: 'string | description for opt1',

      /* value为 Object 类型时 */
      opt2: {
        type: 'string',               // 选项值类型，默认为string
        short: 'o2',                  // 选项简写，默认为key首字母小写
        default: 'default',           // 选项的默认值
        description: 'desc for opt2', // 选项的描述
        oneof: ['yes', 'no'],         // 设置选项的取值范围
      },
    },

    /* 解析命令行的 参数 和 选项，并作为处理函数的参数 */
    (args, opts) => {
        const { arg1, arg2 } = args;
        const { opt1, opt2 } = opts;
        console.log(typeof arg1 === 'string');
        console.log(typeof opt1 === 'string');
    }
);

Handler

每注册一个命令都需要添加该命令的处理函数 handler，在执行命令行解析的时候，将会分析用户输入的命令、参数和选项，并把解析的结果进行有效性校验，如果正确则构造成相应的参数传递给 handler 处理函数。handler 的第一个参数为 命令参数值，第二个参数为 命令选项值，参数的key值和注册时一致，参数的value值则为注册时所指定的类型和取值范围。

commander.registry(
    'check',
    { arg1: 'string' },
    { opt1: 'number' },
    
    /*--------- 命令处理函数 ---------*/
    (args, opts) => {
        console.log('参数值：', args.arg1); // 注册参数的取值
        console.log('选项值：', opts.opt1); // 注册选项的取值
    }
);

commander.addCommand() -> Commander

除了通过registry注册命令外，我们还可以直接通过该方法添加Command类实例新增命令。

import { Command } from '@fxtop/commaner';

commander.addCommand(
  new Command().version('1.0.0'),
);

commander.execute() -> void

执行命令行解析操作，并触发相应的命令处理函数。

support

当前版本支持 Nodejs 8.0.0 以上的版本，使用过程中请确保 Nodejs 的版本号，如果低于 8.0.0 版本，请先进行版本升级后再使用。

feature

@fxtop/commaner@0.1.0

• 支持简单快速注册 命令
• 支持 参数 和 选项 的配置
• 支持绑定命令 处理函数

issues

暂无，希望广大网友发布问题可以提Issue，我将尽快解决并发布。

license

Copyright (c) 2020 Louis (wechat: Faxin_Tan) Licensed under the MIT license.