breadc 0.0.0 → 0.2.0

package/README.md

@@ -1,8 +1,8 @@
 # Breadc
 
-[![CI](https://github.com/yjl9903/Breadc/actions/workflows/ci.yml/badge.svg)](https://github.com/yjl9903/Breadc/actions/workflows/ci.yml)
+[![version](https://img.shields.io/npm/v/breadc?color=rgb%2850%2C203%2C86%29&label=Breadc)](https://www.npmjs.com/package/breadc) [![CI](https://github.com/yjl9903/Breadc/actions/workflows/ci.yml/badge.svg)](https://github.com/yjl9903/Breadc/actions/workflows/ci.yml)
 
-Yet another Command Line Application Framework powered by [minimist](https://www.npmjs.com/package/minimist).
+Yet another Command Line Application Framework powered by [minimist](https://www.npmjs.com/package/minimist), but with fully [TypeScript](https://www.typescriptlang.org/) support.
 
 ## Installation
 
@@ -12,14 +12,57 @@ npm i breadc
 
 ## Usage
 
+Try [./examples/echo.ts](./examples/echo.ts).
+
 ```ts
 import Breadc from 'breadc'
 
-const cli = Breadc('cli', { version: '1.0.0' })
+const cli = Breadc('echo', { version: '1.0.0' })
+  .option('--host <host>')
+  .option('--port <port>')
+
+cli
+  .command('[message]')
+  .action((message, option) => {
+    const host = option.host;
+    const port = option.port;
+    console.log(`Host: ${host}`);
+    console.log(`Port: ${port}`);
+  })
+
+cli.run(process.argv.slice(2))
+  .catch(err => cli.logger.error(err.message))
+```
+
+If you are using IDEs that support TypeScript (like [Visual Studio Code](https://code.visualstudio.com/)), move your cursor to the parameter `option` in the default command, and then you will find the `option` is automatically typed with `{ host: string | boolean, port: string | boolean }`.
+
+![vscode](./images/vscode.png)
+
+### Limitation
 
-cli.parse(process.argv.slice(2))
+For the limitation of TypeScript, in the command format string, you can only write up to **5** pieces. That is to say, you can only write format string like `<p1> <p2> <p3> <p4> [p5]`, but `<p1> <p2> <p3> <p4> <p5> [p6]` does not work.
+
+You should always use method chaining when registering options and commands. The example below will fail to infer the option `--host`.
+
+```ts
+const cli = Breadc('cli')
+
+cli
+  .option('--host')
+
+cli
+  .option('--port')
+  .command('')
+  .action((option) => {
+    // The type of option is Record<'port', string>
+  })
 ```
 
+## Inspiration
+
++ [cac](https://github.com/cacjs/cac): Simple yet powerful framework for building command-line apps.
++ [TypeScript: Documentation - Template Literal Types](https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html)
+
 ## License
 
 MIT License © 2021 [XLor](https://github.com/yjl9903)

package/dist/index.cjs

@@ -1,62 +1,404 @@
 'use strict';
 
+Object.defineProperty(exports, '__esModule', { value: true });
+
+const kolorist = require('kolorist');
 const minimist = require('minimist');
+const createDebug = require('debug');
 
 function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e["default"] : e; }
 
+const kolorist__default = /*#__PURE__*/_interopDefaultLegacy(kolorist);
 const minimist__default = /*#__PURE__*/_interopDefaultLegacy(minimist);
+const createDebug__default = /*#__PURE__*/_interopDefaultLegacy(createDebug);
+
+function createDefaultLogger(name, logger) {
+  if (!!logger && typeof logger === "object") {
+    return logger;
+  }
+  const debug = createDebug__default(name + ":breadc");
+  const println = !!logger && typeof logger === "function" ? logger : (message, ...args) => {
+    console.log(message, ...args);
+  };
+  return {
+    println,
+    info(message, ...args) {
+      println(`${kolorist.blue("INFO")} ${message}`, ...args);
+    },
+    warn(message, ...args) {
+      println(`${kolorist.yellow("WARN")} ${message}`, ...args);
+    },
+    error(message, ...args) {
+      println(`${kolorist.red("ERROR")} ${message}`, ...args);
+    },
+    debug(message, ...args) {
+      debug(message, ...args);
+    }
+  };
+}
+
+const _Option = class {
+  constructor(format, config = {}) {
+    this.format = format;
+    const match = _Option.OptionRE.exec(format);
+    if (match) {
+      if (match[3]) {
+        this.type = "string";
+      } else {
+        this.type = "boolean";
+      }
+      this.name = match[2];
+      if (match[1]) {
+        this.shortcut = match[1][1];
+      }
+    } else {
+      throw new Error(`Can not parse option format from "${format}"`);
+    }
+    this.description = config.description ?? "";
+    this.required = format.indexOf("<") !== -1;
+    this.default = config.default;
+    this.construct = config.construct ?? ((text) => text ?? config.default ?? void 0);
+  }
+};
+let Option = _Option;
+Option.OptionRE = /^(-[a-zA-Z], )?--([a-zA-Z.]+)( \[[a-zA-Z]+\]| <[a-zA-Z]+>)?$/;
+
+const _Command = class {
+  constructor(format, config) {
+    this.options = [];
+    this.format = config.condition ? [format] : format.split(" ").map((t) => t.trim()).filter(Boolean);
+    this.default = this.format.length === 0 || this.format[0][0] === "[" || this.format[0][0] === "<";
+    this.description = config.description ?? "";
+    this.conditionFn = config.condition;
+    this.logger = config.logger;
+    if (this.format.length > _Command.MaxDep) {
+      this.logger.warn(`Command format string "${format}" is too long`);
+    }
+  }
+  option(format, configOrDescription = "", otherConfig = {}) {
+    const config = typeof configOrDescription === "object" ? configOrDescription : { ...otherConfig, description: configOrDescription };
+    try {
+      const option = new Option(format, config);
+      this.options.push(option);
+    } catch (error) {
+      this.logger.warn(error.message);
+    }
+    return this;
+  }
+  get hasConditionFn() {
+    return !!this.conditionFn;
+  }
+  shouldRun(args) {
+    if (this.conditionFn) {
+      return this.conditionFn(args);
+    } else {
+      if (this.default)
+        return true;
+      const isCmd = (t) => t[0] !== "[" && t[0] !== "<";
+      for (let i = 0; i < this.format.length; i++) {
+        if (!isCmd(this.format[i])) {
+          return true;
+        }
+        if (i >= args["_"].length || this.format[i] !== args["_"][i]) {
+          return false;
+        }
+      }
+      return true;
+    }
+  }
+  parseArgs(args, globalOptions) {
+    if (this.conditionFn) {
+      const argumentss2 = args["_"];
+      const options2 = args;
+      delete options2["_"];
+      return {
+        command: this,
+        arguments: argumentss2,
+        options: args
+      };
+    }
+    const isCmd = (t) => t[0] !== "[" && t[0] !== "<";
+    const argumentss = [];
+    for (let i = 0; i < this.format.length; i++) {
+      if (isCmd(this.format[i]))
+        continue;
+      if (i < args["_"].length) {
+        if (this.format[i].startsWith("[...")) {
+          argumentss.push(args["_"].slice(i).map(String));
+        } else {
+          argumentss.push(String(args["_"][i]));
+        }
+      } else {
+        if (this.format[i].startsWith("<")) {
+          this.logger.warn(`You should provide the argument "${this.format[i]}"`);
+          argumentss.push(void 0);
+        } else if (this.format[i].startsWith("[...")) {
+          argumentss.push([]);
+        } else if (this.format[i].startsWith("[")) {
+          argumentss.push(void 0);
+        } else {
+          this.logger.warn(`unknown format string ("${this.format[i]}")`);
+        }
+      }
+    }
+    const fullOptions = globalOptions.concat(this.options).reduce((map, o) => {
+      map.set(o.name, o);
+      return map;
+    }, /* @__PURE__ */ new Map());
+    const options = args;
+    delete options["_"];
+    for (const [name, rawOption] of fullOptions) {
+      if (rawOption.required) {
+        if (options[name] === void 0) {
+          options[name] = false;
+        } else if (options[name] === "") {
+          options[name] = true;
+        }
+      } else {
+        if (options[name] === false) {
+          options[name] = void 0;
+        } else if (!(name in options)) {
+          options[name] = void 0;
+        }
+      }
+    }
+    return {
+      command: this,
+      arguments: argumentss,
+      options
+    };
+  }
+  action(fn) {
+    this.actionFn = fn;
+    return this;
+  }
+  async run(...args) {
+    if (this.actionFn) {
+      this.actionFn(...args);
+    } else {
+      this.logger.warn(`You may miss action function in "${this.format}"`);
+    }
+  }
+};
+let Command = _Command;
+Command.MaxDep = 5;
+function createHelpCommand(breadc) {
+  let helpCommand = void 0;
+  return new Command("-h, --help", {
+    condition(args) {
+      const isEmpty = !args["--"]?.length;
+      if ((args.help || args.h) && isEmpty) {
+        if (args["_"].length > 0) {
+          for (const cmd of breadc.commands) {
+            if (!cmd.hasConditionFn && !cmd.default && cmd.shouldRun(args)) {
+              helpCommand = cmd;
+              return true;
+            }
+          }
+        }
+        return true;
+      } else {
+        return false;
+      }
+    },
+    logger: breadc.logger
+  }).action(() => {
+    for (const line of breadc.help(helpCommand)) {
+      breadc.logger.println(line);
+    }
+  });
+}
+function createVersionCommand(breadc) {
+  return new Command("-v, --version", {
+    condition(args) {
+      const isEmpty = !args["_"].length && !args["--"]?.length;
+      if (args.version && isEmpty) {
+        return true;
+      } else if (args.v && isEmpty) {
+        return true;
+      } else {
+        return false;
+      }
+    },
+    logger: breadc.logger
+  }).action(() => {
+    breadc.logger.println(breadc.version());
+  });
+}
 
 class Breadc {
   constructor(name, option) {
     this.options = [];
+    this.commands = [];
     this.name = name;
-    this.version = option.version;
+    this._version = option.version ?? "unknown";
+    this.description = option.description;
+    this.logger = createDefaultLogger(name, option.logger);
+    const breadc = {
+      name: this.name,
+      version: () => this.version.call(this),
+      help: (command) => this.help.call(this, command),
+      logger: this.logger,
+      options: this.options,
+      commands: this.commands
+    };
+    this.commands.push(createVersionCommand(breadc), createHelpCommand(breadc));
+  }
+  version() {
+    return `${this.name}/${this._version}`;
+  }
+  help(command) {
+    const output = [];
+    const println = (msg) => output.push(msg);
+    println(this.version());
+    if (!command) {
+      if (this.description) {
+        println("");
+        if (Array.isArray(this.description)) {
+          for (const line of this.description) {
+            println(line);
+          }
+        } else {
+          println(this.description);
+        }
+      }
+    } else {
+      if (command.description) {
+        println("");
+        println(command.description);
+      }
+    }
+    if (!command) {
+      if (this.defaultCommand) {
+        println(``);
+        println(`Usage:`);
+        println(`  $ ${this.name} ${this.defaultCommand.format.join(" ")}`);
+      }
+    } else {
+      println(``);
+      println(`Usage:`);
+      println(`  $ ${this.name} ${command.format.join(" ")}`);
+    }
+    if (!command && this.commands.length > 2) {
+      println(``);
+      println(`Commands:`);
+      const commandHelps = this.commands.filter((c) => !c.hasConditionFn).map((c) => [`  $ ${this.name} ${c.format.join(" ")}`, c.description]);
+      for (const line of twoColumn(commandHelps)) {
+        println(line);
+      }
+    }
+    println(``);
+    println(`Options:`);
+    const optionHelps = [].concat([
+      ...command ? command.options.map((o) => [`  ${o.format}`, o.description]) : [],
+      ...this.options.map((o) => [`  ${o.format}`, o.description]),
+      [`  -h, --help`, `Display this message`],
+      [`  -v, --version`, `Display version number`]
+    ]);
+    for (const line of twoColumn(optionHelps)) {
+      println(line);
+    }
+    println(``);
+    return output;
   }
-  option(text) {
+  option(format, configOrDescription = "", otherConfig = {}) {
+    const config = typeof configOrDescription === "object" ? configOrDescription : { ...otherConfig, description: configOrDescription };
     try {
-      const option = new BreadcOption(text);
+      const option = new Option(format, config);
       this.options.push(option);
     } catch (error) {
+      this.logger.warn(error.message);
     }
     return this;
   }
-  command(text) {
-    return new Breadcommand(this, text);
+  command(format, configOrDescription = "", otherConfig = {}) {
+    const config = typeof configOrDescription === "object" ? configOrDescription : { ...otherConfig, description: configOrDescription };
+    const command = new Command(format, { ...config, logger: this.logger });
+    if (command.default) {
+      if (this.defaultCommand) {
+        this.logger.warn("You can not have two default commands.");
+      }
+      this.defaultCommand = command;
+    }
+    this.commands.push(command);
+    return command;
   }
   parse(args) {
+    const allowOptions = [
+      ...this.options,
+      ...this.commands.flatMap((c) => c.options)
+    ];
+    const alias = allowOptions.reduce((map, o) => {
+      if (o.shortcut) {
+        map[o.shortcut] = o.name;
+      }
+      return map;
+    }, {});
+    const defaults = allowOptions.reduce((map, o) => {
+      if (o.default) {
+        map[o.name] = o.default;
+      }
+      return map;
+    }, {});
     const argv = minimist__default(args, {
-      string: this.options.filter((o) => o.type === "string").map((o) => o.name),
-      boolean: this.options.filter((o) => o.type === "boolean").map((o) => o.name)
+      string: allowOptions.filter((o) => o.type === "string").map((o) => o.name),
+      boolean: allowOptions.filter((o) => o.type === "boolean").map((o) => o.name),
+      alias,
+      default: defaults,
+      unknown: (t) => {
+        if (t[0] !== "-")
+          return true;
+        else {
+          if (["--help", "-h", "--version", "-v"].includes(t)) {
+            return true;
+          } else {
+            this.logger.warn(`Find unknown flag "${t}"`);
+            return false;
+          }
+        }
+      }
     });
-    return argv;
-  }
-}
-class Breadcommand {
-  constructor(breadc, text) {
-    this.breadc = breadc;
-  }
-}
-const _BreadcOption = class {
-  constructor(text) {
-    if (_BreadcOption.BooleanRE.test(text)) {
-      this.type = "boolean";
-    } else {
-      this.type = "string";
+    for (const shortcut of Object.keys(alias)) {
+      delete argv[shortcut];
     }
-    const match = _BreadcOption.NameRE.exec(text);
-    if (match) {
-      this.name = match[1];
-    } else {
-      throw new Error(`Can not extract option name from "${text}"`);
+    for (const command of this.commands) {
+      if (!command.default && command.shouldRun(argv)) {
+        return command.parseArgs(argv, this.options);
+      }
     }
+    if (this.defaultCommand) {
+      return this.defaultCommand.parseArgs(argv, this.options);
+    }
+    const argumentss = argv["_"];
+    const options = argv;
+    delete options["_"];
+    return {
+      command: void 0,
+      arguments: argumentss,
+      options
+    };
   }
-};
-let BreadcOption = _BreadcOption;
-BreadcOption.BooleanRE = /^--[a-zA-Z.]+$/;
-BreadcOption.NameRE = /--([a-zA-Z.]+)/;
+  async run(args) {
+    const parsed = this.parse(args);
+    if (parsed.command) {
+      parsed.command.run(...parsed.arguments, parsed.options);
+    }
+  }
+}
+function twoColumn(texts, split = "  ") {
+  const left = padRight(texts.map((t) => t[0]));
+  return left.map((l, idx) => l + split + texts[idx][1]);
+}
+function padRight(texts, fill = " ") {
+  const length = texts.map((t) => t.length).reduce((max, l) => Math.max(max, l), 0);
+  return texts.map((t) => t + fill.repeat(length - t.length));
+}
 
 function breadc(name, option = {}) {
-  return new Breadc(name, { version: option.version ?? "unknown" });
+  return new Breadc(name, option);
 }
 
-module.exports = breadc;
+exports.kolorist = kolorist__default;
+exports.minimist = minimist__default;
+exports.createDebug = createDebug__default;
+exports["default"] = breadc;

package/dist/index.d.ts

@@ -1,24 +1,123 @@
-import minimist from 'minimist';
+import { ParsedArgs } from 'minimist';
+export { default as minimist } from 'minimist';
+export { default as kolorist } from 'kolorist';
+export { default as createDebug } from 'debug';
 
-declare class Breadc {
-    private readonly name;
-    private readonly version;
-    private readonly options;
-    constructor(name: string, option: {
-        version: string;
-    });
-    option(text: string): this;
-    command(text: string): Breadcommand;
-    parse(args: string[]): minimist.ParsedArgs;
+interface OptionConfig<T = string> {
+    description?: string;
+    default?: T;
+    construct?: (rawText?: string) => T;
+}
+/**
+ * Option
+ *
+ * Option format must follow:
+ * + --option
+ * + -o, --option
+ * + --option <arg>
+ * + --option [arg]
+ */
+declare class Option<T extends string = string, F = string> {
+    private static OptionRE;
+    readonly name: string;
+    readonly shortcut?: string;
+    readonly default?: F;
+    readonly format: string;
+    readonly description: string;
+    readonly type: 'string' | 'boolean';
+    readonly required: boolean;
+    readonly construct: (rawText: string | undefined) => any;
+    constructor(format: T, config?: OptionConfig<F>);
 }
-declare class Breadcommand {
-    private readonly breadc;
-    constructor(breadc: Breadc, text: string);
+
+declare type ConditionFn = (args: ParsedArgs) => boolean;
+interface CommandConfig {
+    description?: string;
+}
+declare class Command<F extends string = string, CommandOption extends object = {}> {
+    private static MaxDep;
+    private readonly conditionFn?;
+    private readonly logger;
+    readonly format: string[];
+    readonly default: boolean;
+    readonly description: string;
+    readonly options: Option[];
+    private actionFn?;
+    constructor(format: F, config: CommandConfig & {
+        condition?: ConditionFn;
+        logger: Logger;
+    });
+    option<OF extends string, T = string>(format: OF, description: string, config?: Omit<OptionConfig<T>, 'description'>): Command<F, CommandOption & ExtractOption<OF>>;
+    option<OF extends string, T = string>(format: OF, config?: OptionConfig<T>): Command<F, CommandOption & ExtractOption<OF>>;
+    get hasConditionFn(): boolean;
+    shouldRun(args: ParsedArgs): boolean;
+    parseArgs(args: ParsedArgs, globalOptions: Option[]): ParseResult;
+    action(fn: ActionFn<ExtractCommand<F>, CommandOption>): this;
+    run(...args: any[]): Promise<void>;
 }
 
-interface Option {
+interface AppOption {
     version?: string;
+    description?: string | string[];
+    help?: string | string[] | (() => string | string[]);
+    logger?: Logger | LoggerFn;
 }
-declare function breadc(name: string, option?: Option): Breadc;
+declare type LoggerFn = (message: string, ...args: any[]) => void;
+interface Logger {
+    println: LoggerFn;
+    info: LoggerFn;
+    warn: LoggerFn;
+    error: LoggerFn;
+    debug: LoggerFn;
+}
+interface ParseResult {
+    command: Command | undefined;
+    arguments: any[];
+    options: Record<string, string>;
+}
+declare type ExtractOption<T extends string> = {
+    [k in ExtractOptionName<T>]: ExtractOptionType<T>;
+};
+/**
+ * Extract option name type
+ *
+ * Examples:
+ * + const t1: ExtractOption<'--option' | '--hello'> = 'hello'
+ * + const t2: ExtractOption<'-r, --root'> = 'root'
+ */
+declare type ExtractOptionName<T extends string> = T extends `-${Letter}, --${infer R} [${infer U}]` ? R : T extends `-${Letter}, --${infer R} <${infer U}>` ? R : T extends `-${Letter}, --${infer R}` ? R : T extends `--${infer R} [${infer U}]` ? R : T extends `--${infer R} <${infer U}>` ? R : T extends `--${infer R}` ? R : never;
+declare type ExtractOptionType<T extends string> = T extends `-${Letter}, --${infer R} [${infer U}]` ? string | undefined : T extends `-${Letter}, --${infer R} <${infer U}>` ? string | boolean : T extends `-${Letter}, --${infer R}` ? boolean : T extends `--${infer R} [${infer U}]` ? string | undefined : T extends `--${infer R} <${infer U}>` ? string | boolean : T extends `--${infer R}` ? boolean : never;
+declare type Lowercase = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z';
+declare type Uppercase = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z';
+declare type Letter = Lowercase | Uppercase;
+declare type Push<T extends any[], U> = [...T, U];
+declare type ActionFn<T extends any[], Option extends object = {}> = (...arg: Push<T, Option>) => void;
+/**
+ * Max Dep: 5
+ *
+ * Generated by: npx tsx scripts/genType.ts 5
+ */
+declare type ExtractCommand<T extends string> = T extends `<${infer P1}> <${infer P2}> <${infer P3}> <${infer P4}> [...${infer P5}]` ? [string, string, string, string, string[]] : T extends `<${infer P1}> <${infer P2}> <${infer P3}> <${infer P4}> [${infer P5}]` ? [string, string, string, string, string | undefined] : T extends `<${infer P1}> <${infer P2}> <${infer P3}> <${infer P4}> <${infer P5}>` ? [string, string, string, string, string] : T extends `${infer P1} <${infer P2}> <${infer P3}> <${infer P4}> [...${infer P5}]` ? [string, string, string, string[]] : T extends `${infer P1} <${infer P2}> <${infer P3}> <${infer P4}> [${infer P5}]` ? [string, string, string, string | undefined] : T extends `${infer P1} <${infer P2}> <${infer P3}> <${infer P4}> <${infer P5}>` ? [string, string, string, string] : T extends `${infer P1} ${infer P2} <${infer P3}> <${infer P4}> [...${infer P5}]` ? [string, string, string[]] : T extends `${infer P1} ${infer P2} <${infer P3}> <${infer P4}> [${infer P5}]` ? [string, string, string | undefined] : T extends `${infer P1} ${infer P2} <${infer P3}> <${infer P4}> <${infer P5}>` ? [string, string, string] : T extends `${infer P1} ${infer P2} ${infer P3} <${infer P4}> [...${infer P5}]` ? [string, string[]] : T extends `${infer P1} ${infer P2} ${infer P3} <${infer P4}> [${infer P5}]` ? [string, string | undefined] : T extends `${infer P1} ${infer P2} ${infer P3} <${infer P4}> <${infer P5}>` ? [string, string] : T extends `<${infer P1}> <${infer P2}> <${infer P3}> [...${infer P4}]` ? [string, string, string, string[]] : T extends `<${infer P1}> <${infer P2}> <${infer P3}> [${infer P4}]` ? [string, string, string, string | undefined] : T extends `<${infer P1}> <${infer P2}> <${infer P3}> <${infer P4}>` ? [string, string, string, string] : T extends `${infer P1} <${infer P2}> <${infer P3}> [...${infer P4}]` ? [string, string, string[]] : T extends `${infer P1} <${infer P2}> <${infer P3}> [${infer P4}]` ? [string, string, string | undefined] : T extends `${infer P1} <${infer P2}> <${infer P3}> <${infer P4}>` ? [string, string, string] : T extends `${infer P1} ${infer P2} <${infer P3}> [...${infer P4}]` ? [string, string[]] : T extends `${infer P1} ${infer P2} <${infer P3}> [${infer P4}]` ? [string, string | undefined] : T extends `${infer P1} ${infer P2} <${infer P3}> <${infer P4}>` ? [string, string] : T extends `${infer P1} ${infer P2} ${infer P3} [...${infer P4}]` ? [string[]] : T extends `${infer P1} ${infer P2} ${infer P3} [${infer P4}]` ? [string | undefined] : T extends `${infer P1} ${infer P2} ${infer P3} <${infer P4}>` ? [string] : T extends `<${infer P1}> <${infer P2}> [...${infer P3}]` ? [string, string, string[]] : T extends `<${infer P1}> <${infer P2}> [${infer P3}]` ? [string, string, string | undefined] : T extends `<${infer P1}> <${infer P2}> <${infer P3}>` ? [string, string, string] : T extends `${infer P1} <${infer P2}> [...${infer P3}]` ? [string, string[]] : T extends `${infer P1} <${infer P2}> [${infer P3}]` ? [string, string | undefined] : T extends `${infer P1} <${infer P2}> <${infer P3}>` ? [string, string] : T extends `${infer P1} ${infer P2} [...${infer P3}]` ? [string[]] : T extends `${infer P1} ${infer P2} [${infer P3}]` ? [string | undefined] : T extends `${infer P1} ${infer P2} <${infer P3}>` ? [string] : T extends `${infer P1} ${infer P2} ${infer P3}` ? [] : T extends `<${infer P1}> [...${infer P2}]` ? [string, string[]] : T extends `<${infer P1}> [${infer P2}]` ? [string, string | undefined] : T extends `<${infer P1}> <${infer P2}>` ? [string, string] : T extends `${infer P1} [...${infer P2}]` ? [string[]] : T extends `${infer P1} [${infer P2}]` ? [string | undefined] : T extends `${infer P1} <${infer P2}>` ? [string] : T extends `${infer P1} ${infer P2}` ? [] : T extends `[...${infer P1}]` ? [string[]] : T extends `[${infer P1}]` ? [string | undefined] : T extends `<${infer P1}>` ? [string] : T extends `${infer P1}` ? [] : T extends `` ? [] : never;
+
+declare class Breadc<GlobalOption extends object = {}> {
+    private readonly name;
+    private readonly _version;
+    private readonly description?;
+    private readonly options;
+    private readonly commands;
+    private defaultCommand?;
+    readonly logger: Logger;
+    constructor(name: string, option: AppOption);
+    version(): string;
+    help(command?: Command): string[];
+    option<F extends string, T = string>(format: F, description: string, config?: Omit<OptionConfig<T>, 'description'>): Breadc<GlobalOption & ExtractOption<F>>;
+    option<F extends string, T = string>(format: F, config?: OptionConfig<T>): Breadc<GlobalOption & ExtractOption<F>>;
+    command<F extends string>(format: F, description: string, config?: Omit<CommandConfig, 'description'>): Command<F, GlobalOption>;
+    command<F extends string>(format: F, config?: CommandConfig): Command<F, GlobalOption>;
+    parse(args: string[]): ParseResult;
+    run(args: string[]): Promise<void>;
+}
+
+declare function breadc(name: string, option?: AppOption): Breadc<{}>;
 
 export { breadc as default };

package/dist/index.mjs

@@ -1,56 +1,394 @@
+import { blue, yellow, red } from 'kolorist';
+export { default as kolorist } from 'kolorist';
 import minimist from 'minimist';
+export { default as minimist } from 'minimist';
+import createDebug from 'debug';
+export { default as createDebug } from 'debug';
+
+function createDefaultLogger(name, logger) {
+  if (!!logger && typeof logger === "object") {
+    return logger;
+  }
+  const debug = createDebug(name + ":breadc");
+  const println = !!logger && typeof logger === "function" ? logger : (message, ...args) => {
+    console.log(message, ...args);
+  };
+  return {
+    println,
+    info(message, ...args) {
+      println(`${blue("INFO")} ${message}`, ...args);
+    },
+    warn(message, ...args) {
+      println(`${yellow("WARN")} ${message}`, ...args);
+    },
+    error(message, ...args) {
+      println(`${red("ERROR")} ${message}`, ...args);
+    },
+    debug(message, ...args) {
+      debug(message, ...args);
+    }
+  };
+}
+
+const _Option = class {
+  constructor(format, config = {}) {
+    this.format = format;
+    const match = _Option.OptionRE.exec(format);
+    if (match) {
+      if (match[3]) {
+        this.type = "string";
+      } else {
+        this.type = "boolean";
+      }
+      this.name = match[2];
+      if (match[1]) {
+        this.shortcut = match[1][1];
+      }
+    } else {
+      throw new Error(`Can not parse option format from "${format}"`);
+    }
+    this.description = config.description ?? "";
+    this.required = format.indexOf("<") !== -1;
+    this.default = config.default;
+    this.construct = config.construct ?? ((text) => text ?? config.default ?? void 0);
+  }
+};
+let Option = _Option;
+Option.OptionRE = /^(-[a-zA-Z], )?--([a-zA-Z.]+)( \[[a-zA-Z]+\]| <[a-zA-Z]+>)?$/;
+
+const _Command = class {
+  constructor(format, config) {
+    this.options = [];
+    this.format = config.condition ? [format] : format.split(" ").map((t) => t.trim()).filter(Boolean);
+    this.default = this.format.length === 0 || this.format[0][0] === "[" || this.format[0][0] === "<";
+    this.description = config.description ?? "";
+    this.conditionFn = config.condition;
+    this.logger = config.logger;
+    if (this.format.length > _Command.MaxDep) {
+      this.logger.warn(`Command format string "${format}" is too long`);
+    }
+  }
+  option(format, configOrDescription = "", otherConfig = {}) {
+    const config = typeof configOrDescription === "object" ? configOrDescription : { ...otherConfig, description: configOrDescription };
+    try {
+      const option = new Option(format, config);
+      this.options.push(option);
+    } catch (error) {
+      this.logger.warn(error.message);
+    }
+    return this;
+  }
+  get hasConditionFn() {
+    return !!this.conditionFn;
+  }
+  shouldRun(args) {
+    if (this.conditionFn) {
+      return this.conditionFn(args);
+    } else {
+      if (this.default)
+        return true;
+      const isCmd = (t) => t[0] !== "[" && t[0] !== "<";
+      for (let i = 0; i < this.format.length; i++) {
+        if (!isCmd(this.format[i])) {
+          return true;
+        }
+        if (i >= args["_"].length || this.format[i] !== args["_"][i]) {
+          return false;
+        }
+      }
+      return true;
+    }
+  }
+  parseArgs(args, globalOptions) {
+    if (this.conditionFn) {
+      const argumentss2 = args["_"];
+      const options2 = args;
+      delete options2["_"];
+      return {
+        command: this,
+        arguments: argumentss2,
+        options: args
+      };
+    }
+    const isCmd = (t) => t[0] !== "[" && t[0] !== "<";
+    const argumentss = [];
+    for (let i = 0; i < this.format.length; i++) {
+      if (isCmd(this.format[i]))
+        continue;
+      if (i < args["_"].length) {
+        if (this.format[i].startsWith("[...")) {
+          argumentss.push(args["_"].slice(i).map(String));
+        } else {
+          argumentss.push(String(args["_"][i]));
+        }
+      } else {
+        if (this.format[i].startsWith("<")) {
+          this.logger.warn(`You should provide the argument "${this.format[i]}"`);
+          argumentss.push(void 0);
+        } else if (this.format[i].startsWith("[...")) {
+          argumentss.push([]);
+        } else if (this.format[i].startsWith("[")) {
+          argumentss.push(void 0);
+        } else {
+          this.logger.warn(`unknown format string ("${this.format[i]}")`);
+        }
+      }
+    }
+    const fullOptions = globalOptions.concat(this.options).reduce((map, o) => {
+      map.set(o.name, o);
+      return map;
+    }, /* @__PURE__ */ new Map());
+    const options = args;
+    delete options["_"];
+    for (const [name, rawOption] of fullOptions) {
+      if (rawOption.required) {
+        if (options[name] === void 0) {
+          options[name] = false;
+        } else if (options[name] === "") {
+          options[name] = true;
+        }
+      } else {
+        if (options[name] === false) {
+          options[name] = void 0;
+        } else if (!(name in options)) {
+          options[name] = void 0;
+        }
+      }
+    }
+    return {
+      command: this,
+      arguments: argumentss,
+      options
+    };
+  }
+  action(fn) {
+    this.actionFn = fn;
+    return this;
+  }
+  async run(...args) {
+    if (this.actionFn) {
+      this.actionFn(...args);
+    } else {
+      this.logger.warn(`You may miss action function in "${this.format}"`);
+    }
+  }
+};
+let Command = _Command;
+Command.MaxDep = 5;
+function createHelpCommand(breadc) {
+  let helpCommand = void 0;
+  return new Command("-h, --help", {
+    condition(args) {
+      const isEmpty = !args["--"]?.length;
+      if ((args.help || args.h) && isEmpty) {
+        if (args["_"].length > 0) {
+          for (const cmd of breadc.commands) {
+            if (!cmd.hasConditionFn && !cmd.default && cmd.shouldRun(args)) {
+              helpCommand = cmd;
+              return true;
+            }
+          }
+        }
+        return true;
+      } else {
+        return false;
+      }
+    },
+    logger: breadc.logger
+  }).action(() => {
+    for (const line of breadc.help(helpCommand)) {
+      breadc.logger.println(line);
+    }
+  });
+}
+function createVersionCommand(breadc) {
+  return new Command("-v, --version", {
+    condition(args) {
+      const isEmpty = !args["_"].length && !args["--"]?.length;
+      if (args.version && isEmpty) {
+        return true;
+      } else if (args.v && isEmpty) {
+        return true;
+      } else {
+        return false;
+      }
+    },
+    logger: breadc.logger
+  }).action(() => {
+    breadc.logger.println(breadc.version());
+  });
+}
 
 class Breadc {
   constructor(name, option) {
     this.options = [];
+    this.commands = [];
     this.name = name;
-    this.version = option.version;
+    this._version = option.version ?? "unknown";
+    this.description = option.description;
+    this.logger = createDefaultLogger(name, option.logger);
+    const breadc = {
+      name: this.name,
+      version: () => this.version.call(this),
+      help: (command) => this.help.call(this, command),
+      logger: this.logger,
+      options: this.options,
+      commands: this.commands
+    };
+    this.commands.push(createVersionCommand(breadc), createHelpCommand(breadc));
+  }
+  version() {
+    return `${this.name}/${this._version}`;
+  }
+  help(command) {
+    const output = [];
+    const println = (msg) => output.push(msg);
+    println(this.version());
+    if (!command) {
+      if (this.description) {
+        println("");
+        if (Array.isArray(this.description)) {
+          for (const line of this.description) {
+            println(line);
+          }
+        } else {
+          println(this.description);
+        }
+      }
+    } else {
+      if (command.description) {
+        println("");
+        println(command.description);
+      }
+    }
+    if (!command) {
+      if (this.defaultCommand) {
+        println(``);
+        println(`Usage:`);
+        println(`  $ ${this.name} ${this.defaultCommand.format.join(" ")}`);
+      }
+    } else {
+      println(``);
+      println(`Usage:`);
+      println(`  $ ${this.name} ${command.format.join(" ")}`);
+    }
+    if (!command && this.commands.length > 2) {
+      println(``);
+      println(`Commands:`);
+      const commandHelps = this.commands.filter((c) => !c.hasConditionFn).map((c) => [`  $ ${this.name} ${c.format.join(" ")}`, c.description]);
+      for (const line of twoColumn(commandHelps)) {
+        println(line);
+      }
+    }
+    println(``);
+    println(`Options:`);
+    const optionHelps = [].concat([
+      ...command ? command.options.map((o) => [`  ${o.format}`, o.description]) : [],
+      ...this.options.map((o) => [`  ${o.format}`, o.description]),
+      [`  -h, --help`, `Display this message`],
+      [`  -v, --version`, `Display version number`]
+    ]);
+    for (const line of twoColumn(optionHelps)) {
+      println(line);
+    }
+    println(``);
+    return output;
   }
-  option(text) {
+  option(format, configOrDescription = "", otherConfig = {}) {
+    const config = typeof configOrDescription === "object" ? configOrDescription : { ...otherConfig, description: configOrDescription };
     try {
-      const option = new BreadcOption(text);
+      const option = new Option(format, config);
       this.options.push(option);
     } catch (error) {
+      this.logger.warn(error.message);
     }
     return this;
   }
-  command(text) {
-    return new Breadcommand(this, text);
+  command(format, configOrDescription = "", otherConfig = {}) {
+    const config = typeof configOrDescription === "object" ? configOrDescription : { ...otherConfig, description: configOrDescription };
+    const command = new Command(format, { ...config, logger: this.logger });
+    if (command.default) {
+      if (this.defaultCommand) {
+        this.logger.warn("You can not have two default commands.");
+      }
+      this.defaultCommand = command;
+    }
+    this.commands.push(command);
+    return command;
   }
   parse(args) {
+    const allowOptions = [
+      ...this.options,
+      ...this.commands.flatMap((c) => c.options)
+    ];
+    const alias = allowOptions.reduce((map, o) => {
+      if (o.shortcut) {
+        map[o.shortcut] = o.name;
+      }
+      return map;
+    }, {});
+    const defaults = allowOptions.reduce((map, o) => {
+      if (o.default) {
+        map[o.name] = o.default;
+      }
+      return map;
+    }, {});
     const argv = minimist(args, {
-      string: this.options.filter((o) => o.type === "string").map((o) => o.name),
-      boolean: this.options.filter((o) => o.type === "boolean").map((o) => o.name)
+      string: allowOptions.filter((o) => o.type === "string").map((o) => o.name),
+      boolean: allowOptions.filter((o) => o.type === "boolean").map((o) => o.name),
+      alias,
+      default: defaults,
+      unknown: (t) => {
+        if (t[0] !== "-")
+          return true;
+        else {
+          if (["--help", "-h", "--version", "-v"].includes(t)) {
+            return true;
+          } else {
+            this.logger.warn(`Find unknown flag "${t}"`);
+            return false;
+          }
+        }
+      }
     });
-    return argv;
-  }
-}
-class Breadcommand {
-  constructor(breadc, text) {
-    this.breadc = breadc;
-  }
-}
-const _BreadcOption = class {
-  constructor(text) {
-    if (_BreadcOption.BooleanRE.test(text)) {
-      this.type = "boolean";
-    } else {
-      this.type = "string";
+    for (const shortcut of Object.keys(alias)) {
+      delete argv[shortcut];
     }
-    const match = _BreadcOption.NameRE.exec(text);
-    if (match) {
-      this.name = match[1];
-    } else {
-      throw new Error(`Can not extract option name from "${text}"`);
+    for (const command of this.commands) {
+      if (!command.default && command.shouldRun(argv)) {
+        return command.parseArgs(argv, this.options);
+      }
     }
+    if (this.defaultCommand) {
+      return this.defaultCommand.parseArgs(argv, this.options);
+    }
+    const argumentss = argv["_"];
+    const options = argv;
+    delete options["_"];
+    return {
+      command: void 0,
+      arguments: argumentss,
+      options
+    };
   }
-};
-let BreadcOption = _BreadcOption;
-BreadcOption.BooleanRE = /^--[a-zA-Z.]+$/;
-BreadcOption.NameRE = /--([a-zA-Z.]+)/;
+  async run(args) {
+    const parsed = this.parse(args);
+    if (parsed.command) {
+      parsed.command.run(...parsed.arguments, parsed.options);
+    }
+  }
+}
+function twoColumn(texts, split = "  ") {
+  const left = padRight(texts.map((t) => t[0]));
+  return left.map((l, idx) => l + split + texts[idx][1]);
+}
+function padRight(texts, fill = " ") {
+  const length = texts.map((t) => t.length).reduce((max, l) => Math.max(max, l), 0);
+  return texts.map((t) => t + fill.repeat(length - t.length));
+}
 
 function breadc(name, option = {}) {
-  return new Breadc(name, { version: option.version ?? "unknown" });
+  return new Breadc(name, option);
 }
 
 export { breadc as default };

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "breadc",
-  "version": "0.0.0",
-  "description": "",
+  "version": "0.2.0",
+  "description": "Yet another Command Line Application Framework",
   "keywords": [
-    "cli"
+    "cli",
+    "framework",
+    "command-line",
+    "minimist"
   ],
   "homepage": "https://github.com/yjl9903/Breadc#readme",
   "bugs": {
@@ -30,9 +33,12 @@
     "dist"
   ],
   "dependencies": {
+    "debug": "^4.3.4",
+    "kolorist": "^1.5.1",
     "minimist": "^1.2.6"
   },
   "devDependencies": {
+    "@types/debug": "^4.1.7",
     "@types/minimist": "^1.2.2",
     "@types/node": "^17.0.43",
     "bumpp": "^8.2.1",
@@ -45,7 +51,7 @@
   "packageManager": "pnpm@7.3.0",
   "scripts": {
     "build": "unbuild",
-    "format": "prettier --write src/**/*.ts",
+    "format": "prettier --write src/**/*.ts test/*.ts examples/*.ts scripts/*.ts",
     "release": "bumpp --commit --push --tag && pnpm publish",
     "test": "vitest",
     "typecheck": "tsc --noEmit",