breadc 0.8.9 → 0.9.1

package/dist/index.d.ts

@@ -1,163 +1,221 @@
-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;
-}
-declare class Lexer {
-    private readonly rawArgs;
-    private cursor;
-    constructor(rawArgs: string[]);
-    next(): Token | undefined;
-    hasNext(): boolean;
-    peek(): Token | undefined;
-    [Symbol.iterator](): Iterator<Token, undefined>;
+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;
 }
+declare class Lexer {
+    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];
+} & {};
+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;
 
-interface ParseResult {
-    arguments: Array<string | string[] | undefined>;
-    options: Record<string, any>;
-    '--': string[];
-}
-interface Context {
-    lexer: Lexer;
-    options: Map<string, Option>;
-    result: ParseResult;
-}
-interface TreeNode {
-    command?: Command;
-    children: Map<string, TreeNode>;
-    init(context: Context): void;
-    next(arg: Token, context: Context): TreeNode | false;
-    finish(context: Context): void;
+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[];
+}
+type BreadcParseResult = Prettify<ParseResult & {
+    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;
+}
+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;
 }
 
 declare function makeTreeNode(pnode: Partial<TreeNode>): TreeNode;
 
-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;
-
-/**
- * Extract option type, boolean or string
- */
-type ExtractOptionType<T extends string> = T extends `-${Letter}, --${infer R} <${infer U}>` ? string : T extends `-${Letter}, --${infer R}` ? boolean : T extends `--${infer R} <${infer U}>` ? string : T extends `--${infer R}` ? boolean : string | boolean;
-/**
- * Extract option raw name
- *
- * Examples:
- * + const t1: ExtractOption<'--option' | '--hello'> = 'hello'
- * + const t2: ExtractOption<'-r, --root'> = 'root'
- * + const t3: ExtractOption<'--page-index'> = 'pageIndex'
- */
-type ExtractOptionRawName<T extends string> = T extends `-${Letter}, --${infer R} <${infer U}>` ? R : T extends `-${Letter}, --no-${infer R}` ? R : T extends `-${Letter}, --${infer R}` ? R : T extends `--${infer R} <${infer U}>` ? R : T extends `--no-${infer R}` ? R : T extends `--${infer R}` ? R : never;
-/**
- * Extrat camel case option name
- */
-type ExtractOptionName<T extends string, R extends string = ExtractOptionRawName<T>> = R extends `${infer P1}-${infer P2}-${infer P3}` ? `${P1}${Capitalize<P2>}${Capitalize<P3>}` : R extends `${infer P1}-${infer P2}` ? `${P1}${Capitalize<P2>}` : R;
-/**
- * Extract option information
- */
-type ExtractOption<T extends string, D = undefined> = {
-    [k in ExtractOptionName<T>]: D extends undefined ? 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[];
-}>, {}>) => R | Promise<R>;
-/**
- * Max Dep: 5
- *
- * Generated by: npx tsx examples/genType.ts 5
- */
+/**
+ * Extract option type, boolean or string
+ */
+type ExtractOptionType<T extends string> = T extends `-${Letter}, --${infer R} <${infer U}>` ? string : T extends `-${Letter}, --${infer R}` ? boolean : T extends `--${infer R} <${infer U}>` ? string : T extends `--${infer R}` ? boolean : string | boolean;
+/**
+ * Extract option raw name
+ *
+ * Examples:
+ * + const t1: ExtractOption<'--option' | '--hello'> = 'hello'
+ * + const t2: ExtractOption<'-r, --root'> = 'root'
+ * + const t3: ExtractOption<'--page-index'> = 'pageIndex'
+ */
+type ExtractOptionRawName<T extends string> = T extends `-${Letter}, --${infer R} <${infer U}>` ? R : T extends `-${Letter}, --no-${infer R}` ? R : T extends `-${Letter}, --${infer R}` ? R : T extends `--${infer R} <${infer U}>` ? R : T extends `--no-${infer R}` ? R : T extends `--${infer R}` ? R : never;
+/**
+ * Extrat camel case option name
+ */
+type ExtractOptionName<T extends string, R extends string = ExtractOptionRawName<T>> = R extends `${infer P1}-${infer P2}-${infer P3}` ? `${P1}${Capitalize<P2>}${Capitalize<P3>}` : R extends `${infer P1}-${infer P2}` ? `${P1}${Capitalize<P2>}` : R;
+/**
+ * Extract option information
+ */
+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[];
+}>, {}>) => R | Promise<R>;
+/**
+ * Max Dep: 5
+ *
+ * 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;
 
-interface AppOption {
-    version?: string;
-    description?: string;
-    plugins?: Partial<Plugin>[];
-}
-interface Breadc<GlobalOption extends object = {}> {
-    name: string;
-    description: string;
-    option<F extends string = string, T extends string | boolean = ExtractOptionType<F>, R extends any = ExtractOptionType<F>>(format: F, description?: string, option?: OptionOption<T, R>): Breadc<GlobalOption & ExtractOption<F, R>>;
-    option<F extends string = string, T extends string | boolean = ExtractOptionType<F>, R extends any = ExtractOptionType<F>>(format: F, option?: OptionOption<T, R>): Breadc<GlobalOption & ExtractOption<F, R>>;
-    command<F extends string = string>(format: F, description?: string): Command<F, ExtractCommand<F>, {}, GlobalOption>;
-    command<F extends string = string>(format: F, option?: CommandOption): Command<F, ExtractCommand<F>, {}, GlobalOption>;
-    parse(args: string[]): {
-        command?: Command;
-    } & ParseResult;
-    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>, 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 {
-    description?: string;
-}
-interface Argument {
-    type: 'const' | 'require' | 'optional' | 'rest';
-    name: string;
-}
-interface Option<F extends string = string, T extends string | boolean = ExtractOptionType<F>, R extends any = T extends string ? string : T extends boolean ? boolean : never> {
-    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;
-    action?: (cursor: TreeNode, token: Token, context: Context) => TreeNode | false;
-}
-interface OptionOption<T extends string | boolean, R extends any = T> {
-    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>;
+interface AppOption {
+    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>;
+}
+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;
+}
+interface CommandOption {
+    description?: string;
+    /**
+     * Config how to handle unknown options
+     */
+    allowUnknownOption?: 'error' | 'skip' | 'rest';
+}
+interface Argument {
+    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;
+}
+interface OptionOption<T extends string | boolean, R extends any = any> {
+    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>;
 }
 
 declare function breadc(name: string, config?: AppOption): Breadc<{}>;
 
 declare function definePlugin(plugin: Partial<Plugin>): Partial<Plugin>;
 
-declare class BreadcError extends Error {
-}
-declare class ParseError extends Error {
+declare class BreadcError extends Error {
+}
+declare class ParseError extends Error {
 }
 
-export { AppOption, Argument, Breadc, BreadcError, Command, Option, ParseError, Plugin, breadc, breadc as default, definePlugin, makeTreeNode };
+export { AppOption, Argument, Breadc, BreadcError, Command, Option, ParseError, Plugin, breadc, definePlugin, makeTreeNode };