breadc 0.8.2 → 0.8.4

package/README.md

@@ -8,7 +8,7 @@ Yet another Command Line Application Framework with fully strong **[TypeScript](
 
 ## Features
 
-+ ⚡️ **Light-weight**: Only 70 kB (Unpacked).
++ ⚡️ **Light-weight**: Only 75 kB (Unpacked).
 + 📖 **East to Learn**: Breadc is basically compatible with [cac](https://github.com/cacjs/cac) and there are only 5 APIs for building a CLI application: `breadc`, `command`, `option`, `action`, `run`.
 + 💻 **TypeScript Infer**: IDE will automatically infer the type of your command action function.
 

package/dist/index.cjs

@@ -128,6 +128,7 @@ class Token {
       return this._type = "string";
     }
   }
+  /* c8 ignore next 1 */
 }
 class Lexer {
   constructor(rawArgs) {
@@ -140,7 +141,7 @@ class Lexer {
     return value ? new Token(value) : void 0;
   }
   hasNext() {
-    return this.cursor + 1 < this.rawArgs.length;
+    return this.cursor < this.rawArgs.length;
   }
   peek() {
     const value = this.rawArgs[this.cursor];
@@ -153,7 +154,7 @@ class Lexer {
         const value = that.rawArgs[that.cursor];
         that.cursor += 1;
         return {
-          value: value ? new Token(value) : void 0,
+          value: value !== void 0 ? new Token(value) : void 0,
           done: that.cursor > that.rawArgs.length
         };
       }
@@ -340,13 +341,13 @@ const initContextOptions = (options, context) => {
 };
 
 function makeCommand(format, config, root, container) {
-  let cursor = root;
   const args = [];
   const options = [];
   const command = {
     callback: void 0,
     format,
     description: config.description ?? "",
+    _default: false,
     _arguments: args,
     _options: options,
     option(format2, _config, _config2 = {}) {
@@ -355,6 +356,21 @@ function makeCommand(format, config, root, container) {
       options.push(option);
       return command;
     },
+    alias(format2) {
+      const aliasArgs = [];
+      const node2 = makeNode(aliasArgs);
+      function* g() {
+        for (const f of format2.split(" ")) {
+          yield { type: "const", name: f };
+        }
+        for (const a of args.filter((a2) => a2.type !== "const")) {
+          yield a;
+        }
+        return void 0;
+      }
+      insertTreeNode(aliasArgs, node2, g());
+      return command;
+    },
     action(fn) {
       command.callback = async (parsed) => {
         await container.preCommand(command, parsed);
@@ -367,78 +383,45 @@ function makeCommand(format, config, root, container) {
       };
     }
   };
-  const node = makeTreeNode({
-    command,
-    init(context) {
-      initContextOptions(options, context);
-    },
-    finish(context) {
-      const rest = context.result["--"];
-      for (let i = 0; i < args.length; i++) {
-        if (args[i].type === "const") {
-          if (rest[i] !== args[i].name) {
-            throw new ParseError(`Sub-command ${args[i].name} mismatch`);
-          }
-        } else if (args[i].type === "require") {
-          if (i >= rest.length) {
-            throw new ParseError(
-              `You must provide require argument ${args[i].name}`
-            );
+  const node = makeNode(args);
+  insertTreeNode(args, node, parseCommandFormat(format));
+  return command;
+  function makeNode(args2) {
+    return makeTreeNode({
+      command,
+      init(context) {
+        initContextOptions(options, context);
+      },
+      finish(context) {
+        const rest = context.result["--"];
+        for (let i = 0; i < args2.length; i++) {
+          if (args2[i].type === "const") {
+            if (rest[i] !== args2[i].name) {
+              throw new ParseError(`Sub-command ${args2[i].name} mismatch`);
+            }
+          } else if (args2[i].type === "require") {
+            if (i >= rest.length) {
+              throw new ParseError(
+                `You must provide require argument ${args2[i].name}`
+              );
+            }
+            context.result.arguments.push(rest[i]);
+          } else if (args2[i].type === "optional") {
+            context.result.arguments.push(rest[i]);
+          } else if (args2[i].type === "rest") {
+            context.result.arguments.push(rest.splice(i));
           }
-          context.result.arguments.push(rest[i]);
-        } else if (args[i].type === "optional") {
-          context.result.arguments.push(rest[i]);
-        } else if (args[i].type === "rest") {
-          context.result.arguments.push(rest.splice(i));
         }
+        context.result["--"] = rest.splice(args2.length);
       }
-      context.result["--"] = rest.splice(args.length);
-    }
-  });
-  {
-    let state = 0;
-    for (let i = 0; i < format.length; i++) {
-      if (format[i] === "<") {
-        if (state !== 0 && state !== 1) {
-          throw new BreadcError(
-            `Required arguments should be placed before optional or rest arguments`
-          );
-        }
-        const start = i;
-        while (i < format.length && format[i] !== ">") {
-          i++;
-        }
-        const name = format.slice(start + 1, i);
-        state = 1;
-        args.push({ type: "require", name });
-      } else if (format[i] === "[") {
-        if (state !== 0 && state !== 1) {
-          throw new BreadcError(
-            `There is at most one optional or rest arguments`
-          );
-        }
-        const start = i;
-        while (i < format.length && format[i] !== "]") {
-          i++;
-        }
-        const name = format.slice(start + 1, i);
-        state = 2;
-        if (name.startsWith("...")) {
-          args.push({ type: "rest", name });
-        } else {
-          args.push({ type: "optional", name });
-        }
-      } else if (format[i] !== " ") {
-        if (state !== 0) {
-          throw new BreadcError(
-            `Sub-command should be placed at the beginning`
-          );
-        }
-        const start = i;
-        while (i < format.length && format[i] !== " ") {
-          i++;
-        }
-        const name = format.slice(start, i);
+    });
+  }
+  function insertTreeNode(args2, node2, parsed) {
+    let cursor = root;
+    for (const arg of parsed) {
+      args2.push(arg);
+      if (arg.type === "const") {
+        const name = arg.name;
         if (cursor.children.has(name)) {
           cursor = cursor.children.get(name);
         } else {
@@ -461,24 +444,70 @@ function makeCommand(format, config, root, container) {
           cursor.children.set(name, internalNode);
           cursor = internalNode;
         }
-        state = 0;
-        args.push({ type: "const", name });
       }
     }
     cursor.command = command;
     if (cursor !== root) {
       for (const [key, value] of cursor.children) {
-        node.children.set(key, value);
+        node2.children.set(key, value);
       }
-      cursor.children = node.children;
-      cursor.next = node.next;
-      cursor.init = node.init;
-      cursor.finish = node.finish;
+      cursor.children = node2.children;
+      cursor.next = node2.next;
+      cursor.init = node2.init;
+      cursor.finish = node2.finish;
     } else {
-      cursor.finish = node.finish;
+      command._default = true;
+      cursor.finish = node2.finish;
     }
   }
-  return command;
+}
+function* parseCommandFormat(format) {
+  let state = 0;
+  for (let i = 0; i < format.length; i++) {
+    if (format[i] === "<") {
+      if (state !== 0 && state !== 1) {
+        throw new BreadcError(
+          `Required arguments should be placed before optional or rest arguments`
+        );
+      }
+      const start = i;
+      while (i < format.length && format[i] !== ">") {
+        i++;
+      }
+      const name = format.slice(start + 1, i);
+      state = 1;
+      yield { type: "require", name };
+    } else if (format[i] === "[") {
+      if (state !== 0 && state !== 1) {
+        throw new BreadcError(
+          `There is at most one optional or rest arguments`
+        );
+      }
+      const start = i;
+      while (i < format.length && format[i] !== "]") {
+        i++;
+      }
+      const name = format.slice(start + 1, i);
+      state = 2;
+      if (name.startsWith("...")) {
+        yield { type: "rest", name };
+      } else {
+        yield { type: "optional", name };
+      }
+    } else if (format[i] !== " ") {
+      if (state !== 0) {
+        throw new BreadcError(`Sub-command should be placed at the beginning`);
+      }
+      const start = i;
+      while (i < format.length && format[i] !== " ") {
+        i++;
+      }
+      const name = format.slice(start, i);
+      state = 0;
+      yield { type: "const", name };
+    }
+  }
+  return void 0;
 }
 function makeVersionCommand(name, config) {
   const command = {
@@ -491,11 +520,12 @@ function makeVersionCommand(name, config) {
     description: "Print version",
     _arguments: [],
     _options: [],
-    option() {
-      return command;
-    },
-    action() {
-    }
+    // @ts-ignore
+    option: void 0,
+    // @ts-ignore
+    alias: void 0,
+    // @ts-ignore
+    action: void 0
   };
   const node = makeTreeNode({
     command,
@@ -517,7 +547,7 @@ function makeVersionCommand(name, config) {
   };
   return option;
 }
-function makeHelpCommand(name, config) {
+function makeHelpCommand(name, config, allCommands) {
   function expandMessage(message) {
     const result = [];
     for (const row of message) {
@@ -556,6 +586,7 @@ function makeHelpCommand(name, config) {
     }
     return commands;
   }
+  const usage = allCommands.length === 0 ? `[OPTIONS]` : allCommands.length === 1 ? `[OPTIONS] ${allCommands[0].format}` : allCommands.some((c) => c._default) ? `[OPTIONS] [COMMAND]` : `[OPTIONS] <COMMAND>`;
   const command = {
     async callback(parsed) {
       const context = parsed.options.__context__;
@@ -569,6 +600,8 @@ function makeHelpCommand(name, config) {
             return void 0;
           }
         },
+        "",
+        `${color.bold(color.underline("Usage:"))} ${color.bold(name)} ${usage}`,
         () => {
           const cmds = expandCommands(cursor);
           if (cmds.length > 0) {
@@ -600,11 +633,12 @@ function makeHelpCommand(name, config) {
     description: "Print help",
     _arguments: [],
     _options: [],
-    option() {
-      return command;
-    },
-    action() {
-    }
+    // @ts-ignore
+    option: void 0,
+    // @ts-ignore
+    alias: void 0,
+    // @ts-ignore
+    action: void 0
   };
   const node = makeTreeNode({
     command,
@@ -631,6 +665,7 @@ function makeHelpCommand(name, config) {
 
 function breadc(name, config = {}) {
   let defaultCommand = void 0;
+  const allCommands = [];
   const globalOptions = [];
   const container = makePluginContainer(config.plugins);
   const root = makeTreeNode({
@@ -640,7 +675,10 @@ function breadc(name, config = {}) {
         initContextOptions(defaultCommand._options, context);
       }
       initContextOptions(
-        [makeHelpCommand(name, config), makeVersionCommand(name, config)],
+        [
+          makeHelpCommand(name, config, allCommands),
+          makeVersionCommand(name, config)
+        ],
         context
       );
     },
@@ -657,9 +695,10 @@ function breadc(name, config = {}) {
     command(text, _config = {}) {
       const config2 = typeof _config === "string" ? { description: _config } : _config;
       const command = makeCommand(text, config2, root, container);
-      if (command._arguments.length === 0 || command._arguments[0].type !== "const") {
+      if (command._default) {
         defaultCommand = command;
       }
+      allCommands.push(command);
       return command;
     },
     parse(args) {

package/dist/index.d.ts

@@ -104,10 +104,12 @@ interface Command<F extends string = string, AT extends any[] = ExtractCommand<F
     callback?: (result: ParseResult) => Promise<any>;
     format: F;
     description: string;
+    _default: boolean;
     _arguments: Argument[];
     _options: Option[];
     option<OF extends string = string, OT extends string | boolean = ExtractOptionType<OF>, OR extends any = ExtractOptionType<OF>>(format: OF, description?: string, option?: OptionOption<OT, OR>): Command<F, AT, CommandOption & ExtractOption<OF, OR>, GlobalOption>;
     option<OF extends string = string, OT extends string | boolean = ExtractOptionType<OF>, OR extends any = ExtractOptionType<OF>>(format: OF, option?: OptionOption<OT, OR>): Command<F, AT, CommandOption & ExtractOption<OF, OR>, GlobalOption>;
+    alias(format: string): Command<F, AT, CommandOption, GlobalOption>;
     action(fn: ActionFn<AT, CommandOption & GlobalOption>): void;
 }
 interface CommandOption {

package/dist/index.mjs

@@ -124,6 +124,7 @@ class Token {
       return this._type = "string";
     }
   }
+  /* c8 ignore next 1 */
 }
 class Lexer {
   constructor(rawArgs) {
@@ -136,7 +137,7 @@ class Lexer {
     return value ? new Token(value) : void 0;
   }
   hasNext() {
-    return this.cursor + 1 < this.rawArgs.length;
+    return this.cursor < this.rawArgs.length;
   }
   peek() {
     const value = this.rawArgs[this.cursor];
@@ -149,7 +150,7 @@ class Lexer {
         const value = that.rawArgs[that.cursor];
         that.cursor += 1;
         return {
-          value: value ? new Token(value) : void 0,
+          value: value !== void 0 ? new Token(value) : void 0,
           done: that.cursor > that.rawArgs.length
         };
       }
@@ -336,13 +337,13 @@ const initContextOptions = (options, context) => {
 };
 
 function makeCommand(format, config, root, container) {
-  let cursor = root;
   const args = [];
   const options = [];
   const command = {
     callback: void 0,
     format,
     description: config.description ?? "",
+    _default: false,
     _arguments: args,
     _options: options,
     option(format2, _config, _config2 = {}) {
@@ -351,6 +352,21 @@ function makeCommand(format, config, root, container) {
       options.push(option);
       return command;
     },
+    alias(format2) {
+      const aliasArgs = [];
+      const node2 = makeNode(aliasArgs);
+      function* g() {
+        for (const f of format2.split(" ")) {
+          yield { type: "const", name: f };
+        }
+        for (const a of args.filter((a2) => a2.type !== "const")) {
+          yield a;
+        }
+        return void 0;
+      }
+      insertTreeNode(aliasArgs, node2, g());
+      return command;
+    },
     action(fn) {
       command.callback = async (parsed) => {
         await container.preCommand(command, parsed);
@@ -363,78 +379,45 @@ function makeCommand(format, config, root, container) {
       };
     }
   };
-  const node = makeTreeNode({
-    command,
-    init(context) {
-      initContextOptions(options, context);
-    },
-    finish(context) {
-      const rest = context.result["--"];
-      for (let i = 0; i < args.length; i++) {
-        if (args[i].type === "const") {
-          if (rest[i] !== args[i].name) {
-            throw new ParseError(`Sub-command ${args[i].name} mismatch`);
-          }
-        } else if (args[i].type === "require") {
-          if (i >= rest.length) {
-            throw new ParseError(
-              `You must provide require argument ${args[i].name}`
-            );
+  const node = makeNode(args);
+  insertTreeNode(args, node, parseCommandFormat(format));
+  return command;
+  function makeNode(args2) {
+    return makeTreeNode({
+      command,
+      init(context) {
+        initContextOptions(options, context);
+      },
+      finish(context) {
+        const rest = context.result["--"];
+        for (let i = 0; i < args2.length; i++) {
+          if (args2[i].type === "const") {
+            if (rest[i] !== args2[i].name) {
+              throw new ParseError(`Sub-command ${args2[i].name} mismatch`);
+            }
+          } else if (args2[i].type === "require") {
+            if (i >= rest.length) {
+              throw new ParseError(
+                `You must provide require argument ${args2[i].name}`
+              );
+            }
+            context.result.arguments.push(rest[i]);
+          } else if (args2[i].type === "optional") {
+            context.result.arguments.push(rest[i]);
+          } else if (args2[i].type === "rest") {
+            context.result.arguments.push(rest.splice(i));
           }
-          context.result.arguments.push(rest[i]);
-        } else if (args[i].type === "optional") {
-          context.result.arguments.push(rest[i]);
-        } else if (args[i].type === "rest") {
-          context.result.arguments.push(rest.splice(i));
         }
+        context.result["--"] = rest.splice(args2.length);
       }
-      context.result["--"] = rest.splice(args.length);
-    }
-  });
-  {
-    let state = 0;
-    for (let i = 0; i < format.length; i++) {
-      if (format[i] === "<") {
-        if (state !== 0 && state !== 1) {
-          throw new BreadcError(
-            `Required arguments should be placed before optional or rest arguments`
-          );
-        }
-        const start = i;
-        while (i < format.length && format[i] !== ">") {
-          i++;
-        }
-        const name = format.slice(start + 1, i);
-        state = 1;
-        args.push({ type: "require", name });
-      } else if (format[i] === "[") {
-        if (state !== 0 && state !== 1) {
-          throw new BreadcError(
-            `There is at most one optional or rest arguments`
-          );
-        }
-        const start = i;
-        while (i < format.length && format[i] !== "]") {
-          i++;
-        }
-        const name = format.slice(start + 1, i);
-        state = 2;
-        if (name.startsWith("...")) {
-          args.push({ type: "rest", name });
-        } else {
-          args.push({ type: "optional", name });
-        }
-      } else if (format[i] !== " ") {
-        if (state !== 0) {
-          throw new BreadcError(
-            `Sub-command should be placed at the beginning`
-          );
-        }
-        const start = i;
-        while (i < format.length && format[i] !== " ") {
-          i++;
-        }
-        const name = format.slice(start, i);
+    });
+  }
+  function insertTreeNode(args2, node2, parsed) {
+    let cursor = root;
+    for (const arg of parsed) {
+      args2.push(arg);
+      if (arg.type === "const") {
+        const name = arg.name;
         if (cursor.children.has(name)) {
           cursor = cursor.children.get(name);
         } else {
@@ -457,24 +440,70 @@ function makeCommand(format, config, root, container) {
           cursor.children.set(name, internalNode);
           cursor = internalNode;
         }
-        state = 0;
-        args.push({ type: "const", name });
       }
     }
     cursor.command = command;
     if (cursor !== root) {
       for (const [key, value] of cursor.children) {
-        node.children.set(key, value);
+        node2.children.set(key, value);
       }
-      cursor.children = node.children;
-      cursor.next = node.next;
-      cursor.init = node.init;
-      cursor.finish = node.finish;
+      cursor.children = node2.children;
+      cursor.next = node2.next;
+      cursor.init = node2.init;
+      cursor.finish = node2.finish;
     } else {
-      cursor.finish = node.finish;
+      command._default = true;
+      cursor.finish = node2.finish;
     }
   }
-  return command;
+}
+function* parseCommandFormat(format) {
+  let state = 0;
+  for (let i = 0; i < format.length; i++) {
+    if (format[i] === "<") {
+      if (state !== 0 && state !== 1) {
+        throw new BreadcError(
+          `Required arguments should be placed before optional or rest arguments`
+        );
+      }
+      const start = i;
+      while (i < format.length && format[i] !== ">") {
+        i++;
+      }
+      const name = format.slice(start + 1, i);
+      state = 1;
+      yield { type: "require", name };
+    } else if (format[i] === "[") {
+      if (state !== 0 && state !== 1) {
+        throw new BreadcError(
+          `There is at most one optional or rest arguments`
+        );
+      }
+      const start = i;
+      while (i < format.length && format[i] !== "]") {
+        i++;
+      }
+      const name = format.slice(start + 1, i);
+      state = 2;
+      if (name.startsWith("...")) {
+        yield { type: "rest", name };
+      } else {
+        yield { type: "optional", name };
+      }
+    } else if (format[i] !== " ") {
+      if (state !== 0) {
+        throw new BreadcError(`Sub-command should be placed at the beginning`);
+      }
+      const start = i;
+      while (i < format.length && format[i] !== " ") {
+        i++;
+      }
+      const name = format.slice(start, i);
+      state = 0;
+      yield { type: "const", name };
+    }
+  }
+  return void 0;
 }
 function makeVersionCommand(name, config) {
   const command = {
@@ -487,11 +516,12 @@ function makeVersionCommand(name, config) {
     description: "Print version",
     _arguments: [],
     _options: [],
-    option() {
-      return command;
-    },
-    action() {
-    }
+    // @ts-ignore
+    option: void 0,
+    // @ts-ignore
+    alias: void 0,
+    // @ts-ignore
+    action: void 0
   };
   const node = makeTreeNode({
     command,
@@ -513,7 +543,7 @@ function makeVersionCommand(name, config) {
   };
   return option;
 }
-function makeHelpCommand(name, config) {
+function makeHelpCommand(name, config, allCommands) {
   function expandMessage(message) {
     const result = [];
     for (const row of message) {
@@ -552,6 +582,7 @@ function makeHelpCommand(name, config) {
     }
     return commands;
   }
+  const usage = allCommands.length === 0 ? `[OPTIONS]` : allCommands.length === 1 ? `[OPTIONS] ${allCommands[0].format}` : allCommands.some((c) => c._default) ? `[OPTIONS] [COMMAND]` : `[OPTIONS] <COMMAND>`;
   const command = {
     async callback(parsed) {
       const context = parsed.options.__context__;
@@ -565,6 +596,8 @@ function makeHelpCommand(name, config) {
             return void 0;
           }
         },
+        "",
+        `${bold(underline("Usage:"))} ${bold(name)} ${usage}`,
         () => {
           const cmds = expandCommands(cursor);
           if (cmds.length > 0) {
@@ -596,11 +629,12 @@ function makeHelpCommand(name, config) {
     description: "Print help",
     _arguments: [],
     _options: [],
-    option() {
-      return command;
-    },
-    action() {
-    }
+    // @ts-ignore
+    option: void 0,
+    // @ts-ignore
+    alias: void 0,
+    // @ts-ignore
+    action: void 0
   };
   const node = makeTreeNode({
     command,
@@ -627,6 +661,7 @@ function makeHelpCommand(name, config) {
 
 function breadc(name, config = {}) {
   let defaultCommand = void 0;
+  const allCommands = [];
   const globalOptions = [];
   const container = makePluginContainer(config.plugins);
   const root = makeTreeNode({
@@ -636,7 +671,10 @@ function breadc(name, config = {}) {
         initContextOptions(defaultCommand._options, context);
       }
       initContextOptions(
-        [makeHelpCommand(name, config), makeVersionCommand(name, config)],
+        [
+          makeHelpCommand(name, config, allCommands),
+          makeVersionCommand(name, config)
+        ],
         context
       );
     },
@@ -653,9 +691,10 @@ function breadc(name, config = {}) {
     command(text, _config = {}) {
       const config2 = typeof _config === "string" ? { description: _config } : _config;
       const command = makeCommand(text, config2, root, container);
-      if (command._arguments.length === 0 || command._arguments[0].type !== "const") {
+      if (command._default) {
         defaultCommand = command;
       }
+      allCommands.push(command);
       return command;
     },
     parse(args) {

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "breadc",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "Yet another Command Line Application Framework with fully strong TypeScript support",
   "keywords": [
     "breadc",
     "cli",
     "framework",
     "command-line",
-    "minimist",
     "typescript"
   ],
   "homepage": "https://github.com/yjl9903/Breadc#readme",
@@ -35,7 +34,7 @@
     "dist"
   ],
   "dependencies": {
-    "@breadc/color": "0.8.2"
+    "@breadc/color": "0.8.4"
   },
   "devDependencies": {
     "@types/node": "^18.11.18",