0.1.2 • Published 6 years ago
@ion-bot/command v0.1.2
@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 } // 解析命令。注意:在不匹配命令名称的情况下将会抛出错误。
}