feat(command): show long help with --help option (#281)

command/README.md

@@ -1225,6 +1225,10 @@ defined by default which prints the help text to stdout. You can also output or
 retrieve the help text programmatically by using the `.showHelp()` or
 `.getHelp()` method.
 
+By default, only the first line of each option and command description is
+printed. With the long help flag (`--help`) the full description is printed for
+each option.
+
 ```typescript
 import { Command } from "https://deno.land/x/cliffy/command/command.ts";
 import { CompletionsCommand } from "https://deno.land/x/cliffy/command/completions/mod.ts";

command/command.ts

@@ -438,8 +438,8 @@ export class Command<
       this.cmd._help = help;
     } else {
       this.cmd.exitOnHelp = help.exit;
-      this.cmd._help = (cmd: Command): string =>
-        HelpGenerator.generate(cmd, help);
+      this.cmd._help = (cmd: Command, options: HelpGeneratorOptions): string =>
+        HelpGenerator.generate(cmd, { ...help, ...options });
     }
     return this;
   }
@@ -979,14 +979,17 @@ export class Command<
           global: true,
           prepend: true,
           action: function () {
-            this.showHelp();
+            this.showHelp({
+              long: this.getRawArgs().includes(`--${helpOption.name}`),
+            });
             if (this.shouldExitOnHelp()) {
               Deno.exit(0);
             }
           },
           ...(this._helpOption?.opts ?? {}),
         },
       );
+      const helpOption = this.options[0];
     }
 
     return this;
@@ -1319,8 +1322,7 @@ export class Command<
   public getShortDescription(): string {
     return this.getDescription()
       .trim()
-      .split("\n")
-      .shift() as string;
+      .split("\n", 1)[0];
   }
 
   /** Get original command-line arguments. */
@@ -1339,14 +1341,14 @@ export class Command<
   }
 
   /** Output generated help without exiting. */
-  public showHelp(): void {
-    console.log(this.getHelp());
+  public showHelp(options?: HelpGeneratorOptions): void {
+    console.log(this.getHelp(options));
   }
 
   /** Get generated help. */
-  public getHelp(): string {
+  public getHelp(options?: HelpGeneratorOptions): string {
     this.registerDefaults();
-    return this.getHelpHandler().call(this, this);
+    return this.getHelpHandler().call(this, this, options ?? {});
   }
 
   /** Get help handler method. */

command/completions/_fish_completions_generator.ts

@@ -132,7 +132,8 @@ ${this.generateCompletions(this.cmd).trim()}`;
       options.required && cmd.push("-r");
       cmd.push("-a", options.arguments);
     }
-    options.description && cmd.push("-d", `'${options.description}'`);
+    options.description &&
+      cmd.push("-d", `'${options.description.split("\n", 1)[0]}'`);
     return cmd.join(" ");
   }
 

command/help/_help_generator.ts

@@ -22,6 +22,7 @@ export interface HelpGeneratorOptions {
   types?: boolean;
   hints?: boolean;
   colors?: boolean;
+  long?: boolean;
 }
 
 /** Help text generator. */
@@ -42,6 +43,7 @@ export class HelpGenerator {
       types: false,
       hints: true,
       colors: true,
+      long: false,
       ...options,
     };
   }
@@ -115,14 +117,16 @@ export class HelpGenerator {
               option.typeDefinition || "",
               this.options.types,
             ),
-            red(bold("-")) + " " +
-            option.description.split("\n").shift() as string,
+            red(bold("-")),
+            this.options.long
+              ? option.description
+              : option.description.split("\n", 1)[0],
             this.generateHints(option),
           ]),
         ])
-          .padding([2, 2, 2])
+          .padding([2, 2, 1, 2])
           .indent(this.indent * 2)
-          .maxColWidth([60, 60, 80, 60])
+          .maxColWidth([60, 60, 1, 80, 60])
           .toString() +
         "\n";
     }
@@ -131,14 +135,16 @@ export class HelpGenerator {
       Table.from([
         ...options.map((option: IOption) => [
           option.flags.map((flag) => blue(flag)).join(", "),
-          red(bold("-")) + " " +
-          option.description.split("\n").shift() as string,
+          red(bold("-")),
+          this.options.long
+            ? option.description
+            : option.description.split("\n", 1)[0],
           this.generateHints(option),
         ]),
       ])
-        .padding([2, 2])
         .indent(this.indent * 2)
-        .maxColWidth([60, 80, 60])
+        .maxColWidth([60, 1, 80, 60])
+        .padding([2, 1, 2])
         .toString() +
       "\n";
   }
@@ -164,12 +170,13 @@ export class HelpGenerator {
               command.getArgsDefinition() || "",
               this.options.types,
             ),
-            red(bold("-")) + " " +
-            command.getDescription().split("\n").shift() as string,
+            red(bold("-")),
+            command.getShortDescription(),
           ]),
         ])
-          .padding([2, 2, 2])
           .indent(this.indent * 2)
+          .maxColWidth([60, 60, 1, 80])
+          .padding([2, 2, 1, 2])
           .toString() +
         "\n";
     }
@@ -179,11 +186,12 @@ export class HelpGenerator {
         ...commands.map((command: Command) => [
           [command.getName(), ...command.getAliases()].map((name) => blue(name))
             .join(", "),
-          red(bold("-")) + " " +
-          command.getDescription().split("\n").shift() as string,
+          red(bold("-")),
+          command.getShortDescription(),
         ]),
       ])
-        .padding([2, 2])
+        .maxColWidth([60, 1, 80])
+        .padding([2, 1, 2])
         .indent(this.indent * 2)
         .toString() +
       "\n";

command/test/integration/command.ts

@@ -7,7 +7,10 @@ const cmd = new Command()
   .description("Completions test.")
   .globalType("color", new EnumType(["blue", "yellow", "red"]))
   .globalOption("-g, --global <val:boolean>", "Foo option.")
-  .option("-m, --main <val:boolean>", "Bar option.")
+  .option(
+    "-m, --main <val:boolean>",
+    "Bar option.\nfoo bar baz. foo bar baz.\n\nfoo bar baz.\nfoo bar baz.",
+  )
   .option("-c, --color <val:color>", "Color option.")
   .default("help")
   // foo

command/test/integration/fixtures/help_option_long.out

@@ -12,6 +12,10 @@
     -V, --version         - Show the version number for this program.                                   
     -g, --global   <val>  - Foo option.                                                                 
     -m, --main     <val>  - Bar option.                                                                 
+                            foo bar baz. foo bar baz.                                                   
+
+                            foo bar baz.                                                                
+                            foo bar baz.                                                                
     -c, --color    <val>  - Color option.                              (Values: "blue", "yellow", "red")
 
   Commands:

command/types.ts

@@ -8,6 +8,7 @@ import type {
 } from "../flags/types.ts";
 import type { Type } from "./type.ts";
 import type { Command } from "./command.ts";
+import type { HelpGeneratorOptions } from "./help/_help_generator.ts";
 
 export type { IDefaultValue, IFlagValueHandler, ITypeHandler, ITypeInfo };
 
@@ -225,7 +226,7 @@ export type IHelpHandler<
   // deno-lint-ignore no-explicit-any
   P extends Command | undefined = any,
   C extends Command<O, A, G, PG, P> = Command<O, A, G, PG, P>,
-> = (this: C, cmd: C) => string;
+> = (this: C, cmd: C, options: HelpGeneratorOptions) => string;
 
 /** Version callback method to print the version. Invoked by the `--help` option command and the `.getVersion()` and `.showHelp()` method's. */
 export type IVersionHandler<