breadc 0.9.7 → 1.0.0-beta.1

package/README.md

@@ -4,7 +4,7 @@
 
 Yet another Command Line Application Framework with fully strong **[TypeScript](https://www.typescriptlang.org/) support**.
 
-![vscode](https://cdn.jsdelivr.net/gh/yjl9903/Breadc/images/vscode.png)
+![vscode](https://cdn.jsdelivr.net/gh/yjl9903/Breadc/assets/typescript.png)
 
 ## Features
 
@@ -24,47 +24,25 @@ npm i breadc
 Try [./examples/echo.ts](./examples/echo.ts).
 
 ```ts
-import { breadc } from 'breadc'
+import { breadc } from 'breadc';
 
 const cli = breadc('echo', { version: '1.0.0' })
-  .option('--host <host>', { default: 'localhost' })
-  .option('--port <port>', { default: '3000', cast: p => +p })
-
-cli
-  .command('[message]', 'Say something!')
-  .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 => console.error(err))
-```
-
-If you are using IDEs that support TypeScript (like [Visual Studio Code](https://code.visualstudio.com/)), input something using `option`, and then you will find the `option` is automatically typed with `{ host: string, port: number }`. In the figure below, [Visual Studio Code](https://code.visualstudio.com/) will automatically infer that the type of `option.host` is `string` and the type of `option.port` is `number`.
-
-![vscode](https://cdn.jsdelivr.net/gh/yjl9903/Breadc/images/vscode.png)
-
-### Limitation
+  .option('--host <host>', 'specify hostname', { initial: 'localhost' })
+  .option('--port <port>', 'specify port', { initial: '3000', cast: (t) => +t });
 
-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.
+cli.command('[message]', 'Say something!').action((message, option) => {
+  console.log(message ?? 'You can say anything!');
+  const { host, port } = option; // { host: string, port: number, '--': string[] }
+  console.log(`Host: ${host}`);
+  console.log(`Port: ${port}`);
+});
 
-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.run(process.argv.slice(2)).catch((err) => console.error(err));
+```
 
-cli
-  .option('--host')
+If you are using IDEs that support TypeScript (like [Visual Studio Code](https://code.visualstudio.com/)), input something using `option`, and then you will find the `option` is automatically typed with `{ host: string, port: number }`. In the figure below, [Visual Studio Code](https://code.visualstudio.com/) will automatically infer that the type of `option.host` is `string` and the type of `option.port` is `number`.
 
-cli
-  .option('--port')
-  .command('')
-  .action((option) => {
-    // The type of option is only { port: boolean }
-  })
-```
+![vscode](https://cdn.jsdelivr.net/gh/yjl9903/Breadc/assets/typescript.png)
 
 ## Inspiration
 

package/dist/index.d.mts

@@ -1,106 +1,109 @@
+//#region src/parser/lexer.d.ts
 type TokenType = '--' | '-' | 'number' | 'string' | 'long' | 'short';
 declare class Token {
-    private readonly text;
-    private _type;
-    constructor(text: string);
-    /**
-     * @returns Raw argument text
-     */
-    raw(): string;
-    /**
-     * @returns Number representation
-     */
-    number(): number;
-    /**
-     * @returns Remove start - for long or short option
-     */
-    option(): string;
-    isOption(): boolean;
-    isText(): boolean;
-    type(): TokenType;
+  private readonly text;
+  private _type;
+  constructor(text: string);
+  /**
+   * @returns Raw argument text
+   */
+  raw(): string;
+  /**
+   * @returns Number representation
+   */
+  number(): number;
+  /**
+   * @returns Remove start - for long or short option
+   */
+  option(): string;
+  isOption(): boolean;
+  isText(): boolean;
+  type(): TokenType;
 }
 declare class Lexer {
-    private readonly rawArgs;
-    private cursor;
-    constructor(rawArgs: string[]);
-    next(): Token | undefined;
-    hasNext(): boolean;
-    peek(): Token | undefined;
-    [Symbol.iterator](): Iterator<Token, undefined>;
+  private readonly rawArgs;
+  private cursor;
+  constructor(rawArgs: string[]);
+  next(): Token | undefined;
+  hasNext(): boolean;
+  peek(): Token | undefined;
+  [Symbol.iterator](): Iterator<Token, undefined>;
 }
-
-type Prettify<T> = {
-    [K in keyof T]: T[K];
-} & {};
+//#endregion
+//#region src/types/utils.d.ts
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
 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';
 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';
 type Letter = Lowercase | Uppercase;
-
+//#endregion
+//#region src/parser/types.d.ts
 type CallbackFn = (result: BreadcParseResult) => any;
 interface ParseResult {
-    /**
-     * Arguments that will be passed to action callback
-     * When parsing, this array is empty
-     */
-    arguments: Array<string | string[] | undefined>;
-    /**
-     * Options map
-     */
-    options: Record<string, any>;
-    /**
-     * Rest arguments.
-     * When parsing, this contains all the non-option arguments
-     */
-    '--': string[];
+  /**
+   * Arguments that will be passed to action callback
+   * When parsing, this array is empty
+   */
+  arguments: Array<string | string[] | undefined>;
+  /**
+   * Options map
+   */
+  options: Record<string, any>;
+  /**
+   * Rest arguments.
+   * When parsing, this contains all the non-option arguments
+   */
+  '--': string[];
 }
 type BreadcParseResult = Prettify<ParseResult & {
-    callback?: CallbackFn;
-    meta: Record<string, any>;
-    matched: {
-        node: TreeNode;
-        command?: Command;
-        option?: Option;
-    };
+  callback?: CallbackFn;
+  meta: Record<string, any>;
+  matched: {
+    node: TreeNode;
+    command?: Command;
+    option?: Option;
+  };
 }>;
 interface Context {
-    /**
-     * Lexer instance
-     */
-    lexer: Lexer;
-    /**
-     * Options supported in the current context
-     */
-    options: Map<string, Option>;
-    /**
-     * Parse result
-     */
-    result: ParseResult;
-    /**
-     * Some other meta information passed
-     */
-    meta: Record<string, any>;
-    /**
-     * Configuration
-     */
-    config: {
-        allowUnknownOption: 'error' | 'skip' | 'rest';
-    };
-    parseOption(cursor: TreeNode, token: Token, context: Context): TreeNode | false;
+  /**
+   * Lexer instance
+   */
+  lexer: Lexer;
+  /**
+   * Options supported in the current context
+   */
+  options: Map<string, Option>;
+  /**
+   * Parse result
+   */
+  result: ParseResult;
+  /**
+   * Some other meta information passed
+   */
+  meta: Record<string, any>;
+  /**
+   * Configuration
+   */
+  config: {
+    allowUnknownOption: 'error' | 'skip' | 'rest';
+  };
+  parseOption(cursor: TreeNode, token: Token, context: Context): TreeNode | false;
 }
 interface TreeNode<F extends CallbackFn = CallbackFn> {
-    command?: Command;
-    option?: Option;
-    /**
-     * Out-going edges from this node
-     */
-    children: Map<string, TreeNode>;
-    init(context: Context): void;
-    next(arg: Token, context: Context): TreeNode | false;
-    finish(context: Context): F | undefined;
+  command?: Command;
+  option?: Option;
+  /**
+   * Out-going edges from this node
+   */
+  children: Map<string, TreeNode>;
+  init(context: Context): void;
+  next(arg: Token, context: Context): TreeNode | false;
+  finish(context: Context): F | undefined;
 }
-
+//#endregion
+//#region src/parser/parser.d.ts
 declare function makeTreeNode(pnode: Partial<TreeNode>): TreeNode;
-
+//#endregion
+//#region src/types/extract.d.ts
 /**
  * Extract option type, boolean or string
  */
@@ -121,12 +124,10 @@ type ExtractOptionName<T extends string, R extends string = ExtractOptionRawName
 /**
  * Extract option information
  */
-type ExtractOption<T extends string, D = never> = {
-    [k in ExtractOptionName<T>]: D extends never ? ExtractOptionType<T> : D;
-};
+type ExtractOption<T extends string, D = never> = { [k in ExtractOptionName<T>]: D extends never ? ExtractOptionType<T> : D };
 type Push<T extends any[], U, R> = [...T, U, R];
 type ActionFn<T extends any[], Option extends object = {}, R = any> = (...arg: Push<T, Prettify<Option & {
-    '--': string[];
+  '--': string[];
 }>, {}>) => R | Promise<R>;
 /**
  * Max Dep: 5
@@ -134,88 +135,90 @@ type ActionFn<T extends any[], Option extends object = {}, R = any> = (...arg: P
  * Generated by: npx tsx examples/genType.ts 5
  */
 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;
-
+//#endregion
+//#region src/types/breadc.d.ts
 interface AppOption {
-    version?: string;
-    description?: string;
-    plugins?: Partial<Plugin>[];
-    builtin?: {
-        version?: false | Partial<{
-            description: string;
-            content: string;
-        }>;
-        help?: false | Partial<{
-            description: string;
-        }>;
-    };
+  version?: string;
+  description?: string;
+  plugins?: Partial<Plugin>[];
+  builtin?: {
+    version?: false | Partial<{
+      description: string;
+      content: string;
+    }>;
+    help?: false | Partial<{
+      description: string;
+    }>;
+  };
 }
 interface Breadc<GlobalOption extends object = {}> {
-    name: string;
-    description: string;
-    option<OF extends string = string, OT extends string | boolean = ExtractOptionType<OF>, OO extends OptionOption<OT, any> = OptionOption<OT, any>, OR extends any = OO extends {
-        cast(...args: any[]): infer CR;
-    } ? CR : OO['default'] extends OT ? OT : OT extends string ? undefined | string : OT extends boolean ? boolean : undefined | string | boolean>(format: OF, description?: string | OO, option?: OO): Breadc<GlobalOption & ExtractOption<OF, OR>>;
-    command<F extends string = string>(format: F, description?: string, option?: CommandOption): Command<F, ExtractCommand<F>, {}, GlobalOption>;
-    command<F extends string = string>(format: F, option?: CommandOption): Command<F, ExtractCommand<F>, {}, GlobalOption>;
-    parse(args: string[]): BreadcParseResult;
-    run<T = any>(args: string[]): Promise<T>;
+  name: string;
+  description: string;
+  option<OF extends string = string, OT extends string | boolean = ExtractOptionType<OF>, OO extends OptionOption<OT, any> = OptionOption<OT, any>, OR extends any = (OO extends {
+    cast(...args: any[]): infer CR;
+  } ? CR : OO['default'] extends OT ? OT : OT extends string ? undefined | string : OT extends boolean ? boolean : undefined | string | boolean)>(format: OF, description?: string | OO, option?: OO): Breadc<GlobalOption & ExtractOption<OF, OR>>;
+  command<F extends string = string>(format: F, description?: string, option?: CommandOption): Command<F, ExtractCommand<F>, {}, GlobalOption>;
+  command<F extends string = string>(format: F, option?: CommandOption): Command<F, ExtractCommand<F>, {}, GlobalOption>;
+  parse(args: string[]): BreadcParseResult;
+  run<T = any>(args: string[]): Promise<T>;
 }
 interface Command<F extends string = string, AT extends any[] = ExtractCommand<F>, CommandOption extends object = {}, GlobalOption extends object = {}> {
-    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>, OO extends OptionOption<OT, any> = OptionOption<OT, any>, OR extends any = OO extends {
-        cast(...args: any[]): infer CR;
-    } ? CR : OO['default'] extends OT ? OT : OT extends string ? undefined | string : OT extends boolean ? boolean : undefined | string | boolean>(format: OF, description?: string | OO, option?: OO): Command<F, AT, CommandOption & ExtractOption<OF, OR>, GlobalOption>;
-    alias(format: string): Command<F, AT, CommandOption, GlobalOption>;
-    action(fn: ActionFn<AT, CommandOption & GlobalOption>): void;
+  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>, OO extends OptionOption<OT, any> = OptionOption<OT, any>, OR extends any = (OO extends {
+    cast(...args: any[]): infer CR;
+  } ? CR : OO['default'] extends OT ? OT : OT extends string ? undefined | string : OT extends boolean ? boolean : undefined | string | boolean)>(format: OF, description?: string | OO, option?: OO): 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 {
-    description?: string;
-    /**
-     * Config how to handle unknown options
-     */
-    allowUnknownOption?: 'error' | 'skip' | 'rest';
+  description?: string;
+  /**
+   * Config how to handle unknown options
+   */
+  allowUnknownOption?: 'error' | 'skip' | 'rest';
 }
 interface Argument {
-    type: 'const' | 'require' | 'optional' | 'rest';
-    name: string;
+  type: 'const' | 'require' | 'optional' | 'rest';
+  name: string;
 }
 interface Option<F extends string = string, T extends string | boolean = ExtractOptionType<F>, R extends unknown = any> {
-    format: F;
-    type: T extends string ? 'string' : T extends boolean ? 'boolean' : never;
-    name: string;
-    short?: string;
-    description: string;
-    order: number;
-    initial?: R;
-    cast?: (value: T extends string ? string : T extends boolean ? boolean : never) => R;
-    parse?: (cursor: TreeNode, token: Token, context: Context) => TreeNode | false;
+  format: F;
+  type: T extends string ? 'string' : T extends boolean ? 'boolean' : never;
+  name: string;
+  short?: string;
+  description: string;
+  order: number;
+  initial?: R;
+  cast?: (value: T extends string ? string : T extends boolean ? boolean : never) => R;
+  parse?: (cursor: TreeNode, token: Token, context: Context) => TreeNode | false;
 }
 interface OptionOption<T extends string | boolean, R extends any = any> {
-    description?: string;
-    default?: T;
-    cast?: (value: T) => R;
+  description?: string;
+  default?: T;
+  cast?: (value: T) => R;
 }
 type CommandHookFn = (result: ParseResult) => void | Promise<void>;
 interface Plugin {
-    onInit?(breadc: Breadc, allCommands: Command[], globalOptions: Option[]): void;
-    onPreRun?(breadc: Breadc): void | Promise<void>;
-    onPreCommand?: Record<string, CommandHookFn> | CommandHookFn;
-    onPostCommand?: Record<string, CommandHookFn> | CommandHookFn;
-    onPostRun?(breadc: Breadc): void | Promise<void>;
+  onInit?(breadc: Breadc, allCommands: Command[], globalOptions: Option[]): void;
+  onPreRun?(breadc: Breadc): void | Promise<void>;
+  onPreCommand?: Record<string, CommandHookFn> | CommandHookFn;
+  onPostCommand?: Record<string, CommandHookFn> | CommandHookFn;
+  onPostRun?(breadc: Breadc): void | Promise<void>;
 }
-
+//#endregion
+//#region src/breadc.d.ts
 declare function breadc(name: string, config?: AppOption): Breadc<{}>;
-
+//#endregion
+//#region src/plugin.d.ts
 declare function definePlugin(plugin: Partial<Plugin>): Partial<Plugin>;
-
-declare class BreadcError extends Error {
-}
-declare class ParseError extends Error {
-}
-
-export { type AppOption, type Argument, type Breadc, BreadcError, type Command, type Option, ParseError, type Plugin, breadc, definePlugin, makeTreeNode };
+//#endregion
+//#region src/error.d.ts
+declare class BreadcError extends Error {}
+declare class ParseError extends Error {}
+//#endregion
+export { type AppOption, type Argument, type Breadc, BreadcError, type Command, type Option, ParseError, type Plugin, breadc, definePlugin, makeTreeNode };