@ion-bot/command

@ion-bot/command 是一个用以解析类 shell 命令的 parser。

与其他 parsers 不同的是，@ion-bot/command 不负责执行具体的行为，而只是以特定的格式解析传入的参数，并以程序可读的对象形式返回。

Introduction

@ion-bot/command 是一个类库，因此你可以这样将其包含进你的项目中：

import IonCommand from '@ion-bot/command'
// 下文均以 command 指代 IonCommand 实例
// declaration 是声明命令的特定格式的字符串，下文将详细声明。
const command = new IonCommand(declaration: string)
// 下文均以 input 指代用户输入的命令
if (command.is(input))
    result = command.parse(input)

Declaration

命令在此处有如下特征：

• 由特定的命令名称开头
• 以空格分隔参数

Declaration 用以描述一个命令。

以下是一个 declaration 示例：

command_name <param1> <param2($)> [optional3] [optional4=abc] -option

其中，除了第一个 command_name 是命令名称外，以 <...> 包裹的是必填参数，以 [...] 包裹的是选填参数（这两类统称为参数）；余下的是开/关选项。剩下的特殊描述格式将逐渐讲解。

Input

Input 是指用户输入的命令。

对于上一例的 declaration，以下是一个可能的 input:

command_name abc $def optional3=ijk -option xyz

IonCommand 解析这段 input 时，做了如下事情：

• 用空格将 input 分割；
• 第 0 项是命令名称 command_name，符合期望；
• 第 1 项被分配到第一个参数 param1；
• 第 2 项以 param2 指定的别名（在 declaration 中，别名在 (...) 里） $ 开头，因此 def 被存储到参数 param2。
• 第 3 项使用了 key=value 的格式，因此 = 后的值 ijk 被分配到 = 前的参数名，optional3。
• 第 4 项是一个选项，因此它被添加到选项列表里。
• 余下的未指定参数 optional4 因为在 declaration 中指定了默认值 =abc，因此 abc 被分配到 optional4。
• 检查到所有必填参数都有值，符合期望，返回结果：

({
    arguments: { // arguments 存储参数
        param1: 'abc',
        param2: 'def',
        optional3: 'ijk',
        optional4: 'abc',
    },
    options: ['-option'], // options 存储选项
    rest: ['xyz'], // rest 存储解析完毕后仍剩余的项目
})

Methods

IonCommand 解析命令的方法如下：

class IonCommand {
    is(input) : boolean // 判断 input 是否匹配命令名称
    parse(input) : { arguments, options, rest } // 解析命令。注意：在不匹配命令名称的情况下将会抛出错误。
}