Clerc:一个轻量但强大的命令行框架

TODO

Clerc项目地址:https://github.com/so1ve/clerc

感觉Clerc写的很牛逼啊,啥功能都有(大嘘

功能列表:

  • 插件化
  • 高度可定制
  • 高度解耦,功能大部分可通过插件实现
  • 链式API
  • 子命令 + 嵌套命令
  • 可切换的单命令 / 多命令模式
  • 自动映射参数
  • 强类型参数、Flag
  • 把Flag转换为驼峰命名
  • 通过plugin-help实现自动生成的帮助
  • 通过plugin-completions实现自动补全
  • 通过plugin-not-found实现在命令未找到的时候给出最接近的命令(即Did you mean
  • 通过plugin-version实现输出版本的命令,及传入--version-V(可自定义)时输出版本号
  • 通过plugin-strict-flags实现在传入多余 / 未定义参数时报错
  • 通过plugin-friendly-error实现错误自动美化输出
  • 以及强大的toolkit(也就是重新导出了一下几个好用的CLI工具(bushi
  • 等等等等……

安装

$ npm install clerc -S
$ yarn add clerc
$ pnpm add clerc

使用

下面是一个最简单的命令:

import { Clerc } from "clerc";

const cli = Clerc.create()
  .name("foo-cli")
  .description("A simple cli")
  .version("1.0.0")
  .command("foo", "A foo command")
  .on("foo", (ctx) => {
    console.log(ctx);
  })
  .parse();

这么几行代码它做了些什么事呢(?)让我们来分析下罢

Clerc.create():没啥好说的,字面意义,创建一个新的Clerc实例

cli.name()cli.description()cli.version():也都是字面意思,分别设置CLI的名称,描述和版本。注意这三个方法是必须调用的,否则会报错=v=

cli.command():这个方法说是Clerc中最重要的方法也不为过,它负责注册命令。它接受1~3个参数。

  • 2~3个参数形式:cli.command(name, description, options?)。其中options的类型为:
type CommandOptions = {
  alias?: string | string[]
  parameters?: string[]
  flags?: Record<string, FlagOptions>
  examples?: [string, string][]
  notes?: string[]
}

alias为一个字符串或一个字符串列表,即该命令的别名

parameters为一个字符串列表,即该命令的参数,格式为<foo>(必选参数),[foo](可选参数),<foo...>(必选展开参数)或[foo...](可选展开参数)。注意可选参数必须在必选参数后,展开参数必须在非展开参数后

flags为命令接受的Flag,一个对象。这个东西我们之后再说

examples为该命令的示例,为一个字符串双层数组,每个元素的格式为[命令示范, 描述]

notes为该命令的一些提示。

  • 单个参数形式:cli.command(commandObject)。这里的commandObject的类型就是上面提到的options类型再加上namedescription两个字段,以及一个handler字段(下面会讲)。为什么要添加一个这么奇怪的形式来注册命令呢?有时你不想把命令都写在一个文件里,这样子可以方便地注册命令。

cli.on(name, handler):当某命令被触发时调用handler。handler的签名为(ctx) => void。其中ctx

算了之后再写,好烦