Added help document generator.

Author: fenying

.vscode/launch.json

@@ -0,0 +1,32 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "[LiteRT/Clap.js] Sample 01 - Commandless",
+            "program": "${workspaceFolder}/src/samples/01-command-less.ts",
+            "cwd": "${workspaceFolder}",
+            "sourceMaps": true,
+            "outFiles": [
+                "${workspaceFolder}/lib/*.js",
+                "${workspaceFolder}/samples/*.js"
+            ]
+        },
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "[LiteRT/Clap.js] Sample 02 - Command help",
+            "program": "${workspaceFolder}/src/samples/02-command.ts",
+            "cwd": "${workspaceFolder}",
+            "sourceMaps": true,
+            "outFiles": [
+                "${workspaceFolder}/lib/*.js",
+                "${workspaceFolder}/samples/*.js"
+            ]
+        }
+    ]
+}

README.md

@@ -15,7 +15,7 @@ npm i @litert/clap --save
 
 ## Documents
 
-- [简体中文版](./docs/zh-CN/index.md)
+Preparing yet.
 
 ## License
 

src/lib/AbstractParser.ts

@@ -31,7 +31,9 @@ export class Option {
 
         public path?: string,
 
-        public parent?: Command
+        public parent?: Command,
+
+        public argName: string = "VALUE"
     ) {
 
     }
@@ -43,12 +45,12 @@ export class Option {
 
     public static isValidName(name: string): boolean {
 
-        return /^[a-zA-Z0-9][-a-zA-Z0-9]+$/.test(name);
+        return /^[a-z0-9][-a-z0-9]+$/i.test(name);
     }
 
     public static isValidShortcut(shortcut: string): boolean {
 
-        return /^[a-zA-Z0-9]$/.test(shortcut);
+        return /^[a-z0-9]$/i.test(shortcut);
     }
 
 }
@@ -73,7 +75,7 @@ export class Command {
 
         public description: string,
 
-        public alias?: string[],
+        public aliases?: string[],
 
         public parent?: Command
     ) {
@@ -99,6 +101,16 @@ export class Command {
         return null;
     }
 
+    public get hasSubCommands(): boolean {
+
+        return !!Object.keys(this.subCommands).length;
+    }
+
+    public get hasOptions(): boolean {
+
+        return !!Object.keys(this.options).length;
+    }
+
     public getOptionByShortcut(shortcut: string): Option | null {
 
         if (this.optionShortcuts[shortcut]) {
@@ -116,12 +128,12 @@ export class Command {
 
     public static isValidName(name: string): boolean {
 
-        return /^[-a-zA-Z0-9]+$/.test(name);
+        return /^[a-z0-9][-a-z0-9]*$/i.test(name);
     }
 
     public static isValidPath(path: string): boolean {
 
-        return /^[-a-zA-Z0-9]+(\.[-a-zA-Z0-9]+)*$/.test(path);
+        return /^[a-z0-9][-a-z0-9]*(\.[a-z0-9][-a-z0-9]*)*$/i.test(path);
     }
 }
 
@@ -143,6 +155,50 @@ export abstract class AbstractParser implements C.IParser {
         this._cmdAliases = {};
         this._options = {};
         this._optionShortcuts = {};
+
+        if (this._config.help.delegated) {
+
+            if (
+                !this._config.help.flag &&
+                !this._config.help.command
+            ) {
+
+                throw new E.E_CONFLICT_CONFIG({
+                    "message": "Must enable at least one of help-command or help-flag."
+                });
+            }
+        }
+
+        if (this._config.help.delegated && this._config.help.flag) {
+
+            this.addOption({
+                "name": "help",
+                "description": "Display the help information.",
+                "shortcut": this._config.help.flagShortchut ? "h" : undefined,
+                "arguments": 0
+            });
+        }
+
+        if (
+            !this._config.options.long.followArgument &&
+            !this._config.options.long.assignArgument
+        ) {
+
+            throw new E.E_CONFLICT_CONFIG({
+                "message": "Must enable at least one of follow-mode or assign-mode."
+            });
+        }
+
+        if (
+            !this._config.options.shortcut.followArgument &&
+            !this._config.options.shortcut.assignArgument &&
+            !this._config.options.shortcut.attachArgument
+        ) {
+
+            throw new E.E_CONFLICT_CONFIG({
+                "message": "Must enable at least one of follow-mode, attach-mode or assign-mode."
+            });
+        }
     }
 
     public addCommand(settings: C.ICommandSettings): this {
@@ -156,7 +212,7 @@ export abstract class AbstractParser implements C.IParser {
 
         if (settings.path) {
 
-            const cmd = this._findCommandByPath(settings.path);
+            const cmd = this._getCommandByPath(settings.path);
 
             if (!cmd) {
 
@@ -249,7 +305,8 @@ export abstract class AbstractParser implements C.IParser {
                     settings,
                     path,
                     optName,
-                    optShortcut
+                    optShortcut,
+                    settings.argumentName
                 );
             }
         }
@@ -258,7 +315,8 @@ export abstract class AbstractParser implements C.IParser {
             this._addOption(
                 settings,
                 optName,
-                optShortcut
+                optShortcut,
+                settings.argumentName
             );
         }
 
@@ -269,10 +327,11 @@ export abstract class AbstractParser implements C.IParser {
         settings: C.IOptionSettings,
         path: string,
         optName: string,
-        optShortcut: string | undefined
+        optShortcut: string | undefined,
+        argName?: string
     ): void {
 
-        const cmd = this._findCommandByPath(path);
+        const cmd = this._getCommandByPath(path);
 
         if (!cmd) {
 
@@ -301,7 +360,8 @@ export abstract class AbstractParser implements C.IParser {
             optShortcut,
             settings.arguments,
             path,
-            cmd
+            cmd,
+            argName
         );
 
         if (optShortcut) {
@@ -313,7 +373,8 @@ export abstract class AbstractParser implements C.IParser {
     protected _addOption(
         settings: C.IOptionSettings,
         optName: string,
-        optShortcut: string | undefined
+        optShortcut: string | undefined,
+        argName?: string
     ): void {
 
         if (this._options[optName]) {
@@ -334,7 +395,10 @@ export abstract class AbstractParser implements C.IParser {
             optName,
             settings.description,
             optShortcut,
-            settings.arguments
+            settings.arguments,
+            undefined,
+            undefined,
+            argName
         );
 
         if (optShortcut) {
@@ -413,7 +477,7 @@ export abstract class AbstractParser implements C.IParser {
         return ret;
     }
 
-    protected _findCommandByPath(path: string): Command | null {
+    protected _getCommandByPath(path: string): Command | null {
 
         path = this._prepareCommandPath(path);
 
@@ -434,5 +498,11 @@ export abstract class AbstractParser implements C.IParser {
         }
     }
 
-    public abstract parse(args: string[]): C.IResult | false;
+    public abstract parse(args: string[]): C.IResult;
+
+    public abstract generateHelp(
+        appName: string,
+        path: string,
+        width?: number
+    ): string[];
 }

src/lib/Common.ts

@@ -76,6 +76,13 @@ export interface IOptionSettings {
      * @default -1
      */
     "arguments"?: number;
+
+    /**
+     * The name for argument, used in HELP documents.
+     *
+     * @default "VALUE"
+     */
+    "argumentName"?: string;
 }
 
 export interface ICommandResult {
@@ -91,6 +98,11 @@ export interface ICommandResult {
 
 export interface IResult {
 
+    /**
+     * Tell if this request showing help document.
+     */
+    "help": string;
+
     /**
      * The parsed commands.
      */
@@ -138,17 +150,22 @@ export interface IParser {
     /**
      * Parse the input arguments.
      *
-     * @returns A `IResult` will be returned when parsed successfully. If help
-     * is handled by the parser, `false` will be returned. When error occurs,
-     * an exception will be thrown.
+     * @returns A `IResult` will be returned when parsed successfully. When
+     * error occurs, an exception will be thrown.
      *
      * @example
      *
      * ```ts
      * parser.parse(process.argv.slice(2));
      * ```
      */
-    parse(args: string[]): IResult | false;
+    parse(args: string[]): IResult;
+
+    generateHelp(
+        appName: string,
+        path: string,
+        width?: number
+    ): string[];
 }
 
 export type DeepPartial<T> = {
@@ -167,21 +184,23 @@ export interface IParserHelpConfig {
      *
      * @default true
      */
-    "useCommand": boolean;
+    "command": boolean;
 
     /**
-     * Use `-h` for shortcut.
+     * Use `--help` (or `-help` when `go` style).
      *
      * @default true
      */
-    "shortFlag": boolean;
+    "flag": boolean;
 
     /**
-     * Use `--help` (or `-help` when `go` style).
+     * Use `-h` for shortcut.
+     *
+     * > Only work while `flag` is set to `true`.
      *
      * @default true
      */
-    "longFlag": boolean;
+    "flagShortchut": boolean;
 }
 
 export interface IParserCommandConfig {

src/lib/Errors.ts

@@ -16,7 +16,7 @@
 
 import * as Core from "@litert/core";
 
-export const ErrorHub = Core.createErrorHub("@litert/clap");
+export const ErrorHub = Core.createErrorHub<Record<string, any>>("@litert/clap");
 
 export const E_DUP_COMMAND_NAME = ErrorHub.define(
     null,
@@ -96,7 +96,7 @@ export const E_EXPECT_OPTION_ARGUMENT = ErrorHub.define(
 export const E_UNKNOWN_COMMAND = ErrorHub.define(
     null,
     "E_UNKNOWN_COMMAND",
-    "Missing the command."
+    "The command doesn't exist."
 );
 
 export const E_TOO_MANY_ARGUMENTS = ErrorHub.define(
@@ -110,3 +110,15 @@ export const E_NO_ENOUGH_ARGUMENTS = ErrorHub.define(
     "E_NO_ENOUGH_ARGUMENTS",
     "The quantity of arguments is not enough."
 );
+
+export const E_COMMAND_EXPECTED = ErrorHub.define(
+    null,
+    "E_COMMAND_EXPECTED",
+    "Missing command or sub command."
+);
+
+export const E_CONFLICT_CONFIG = ErrorHub.define(
+    null,
+    "E_CONFLICT_CONFIG",
+    "The configuration is invalid because it's conflicted."
+);