feat(command): add support to show additional information in help text (

#300)

command/README.md

@@ -83,6 +83,7 @@
 - [Environment variables](#-environment-variables)
 - [Add examples](#-add-examples)
 - [Auto generated help](#-auto-generated-help)
+  - [Additional info](#additional-info)
   - [Customize help](#customize-help)
   - [Help option](#help-option)
   - [Help command](#help-command)
@@ -816,10 +817,9 @@ the top of the auto generated help which defaults to the command arguments.
 ### Arguments
 
 You can use the `.arguments()` method to specify the arguments for the top-level
-and for sub-commands. For sub-commands they can also be included in the
-`.command()` method. Angled brackets (e.g. `<required>`) indicate required input
-and square brackets (e.g. `[optional]`) indicate optional input. A required
-input cannot be defined after an optional input.
+and for sub-commands. Angled brackets (e.g. `<required>`) indicate required
+input and square brackets (e.g. `[optional]`) indicate optional input. A
+required input cannot be defined after an optional input.
 
 ```typescript
 import { Command } from "https://deno.land/x/cliffy/command/mod.ts";
@@ -1304,6 +1304,37 @@ $ deno run https://deno.land/x/cliffy/examples/command/help_option_and_command.t
 
 ![](assets/img/help.gif)
 
+### Additional info
+
+You can add some additional information to the help text with the
+`.meta(name, value)` method.
+
+```ts
+new Command()
+  .name("example")
+  .version("1.0.0")
+  .description("Example command.")
+  .meta("deno", Deno.version.deno)
+  .meta("v8", Deno.version.v8)
+  .meta("typescript", Deno.version.typescript)
+  .parse();
+```
+
+The additional information is displayed below the command version.
+
+```console
+  Usage:   example
+  Version: 0.1.0
+
+  deno: 1.16.1
+  v8: 9.7.106.2
+  typescript: 4.4.2
+
+  Description:
+
+    Example command.
+```
+
 ### Customize help
 
 Customize default help with the `.help()` method.
@@ -1349,9 +1380,9 @@ The `--help` and `-h` option flag prints the auto generated help.
 #### Customize help option
 
 The help option is completely customizable with the `.helpOption()` method. The
-first argument are the flags followed by the description. The third argument can
-be an action handler or an options object. The second and third argument's are
-optional.
+first argument is a string with the flags followed by the description. The third
+argument can be an action handler or an options object. The second and third
+arguments are optional.
 
 ```typescript
 await new Command()

command/command.ts

@@ -135,6 +135,7 @@ export class Command<
   private _helpOption?: IDefaultOption | false;
   private _help?: IHelpHandler;
   private _shouldExit?: boolean;
+  private _meta: Record<string, string> = {};
 
   /** Disable version option. */
   public versionOption(enable: false): this;
@@ -418,6 +419,17 @@ export class Command<
     return this;
   }
 
+  public meta(name: string, value: string): this {
+    this.cmd._meta[name] = value;
+    return this;
+  }
+
+  public getMeta(): Record<string, string>;
+  public getMeta(name: string): string;
+  public getMeta(name?: string): Record<string, string> | string {
+    return typeof name === "undefined" ? this._meta : this._meta[name];
+  }
+
   /**
    * Set command help.
    * @param help Help string, method, or config for generator that returns the help string.

command/help/_help_generator.ts

@@ -52,6 +52,7 @@ export class HelpGenerator {
     const areColorsEnabled = getColorEnabled();
     setColorEnabled(this.options.colors);
     const result = this.generateHeader() +
+      this.generateMeta() +
       this.generateDescription() +
       this.generateOptions() +
       this.generateCommands() +
@@ -84,6 +85,25 @@ export class HelpGenerator {
       "\n";
   }
 
+  private generateMeta(): string {
+    const meta = Object.entries(this.cmd.getMeta());
+    if (!meta.length) {
+      return "";
+    }
+
+    const rows = [];
+    for (const [name, value] of meta) {
+      rows.push([bold(`${name}: `) + value]);
+    }
+
+    return "\n" +
+      Table.from(rows)
+        .indent(this.indent)
+        .padding(1)
+        .toString() +
+      "\n";
+  }
+
   private generateDescription(): string {
     if (!this.cmd.getDescription()) {
       return "";

command/test/integration/command.ts

@@ -5,6 +5,9 @@ const cmd = new Command()
   .version("1.0.0")
   .name("completions-test")
   .description("Completions test.")
+  .meta("meta1", "value1")
+  .meta("meta2", "value2")
+  .meta("meta3", "value3")
   .globalType("color", new EnumType(["blue", "yellow", "red"]))
   .globalOption("-g, --global <val:boolean>", "Foo option.")
   .option(

command/test/integration/fixtures/help_command.out

@@ -2,6 +2,10 @@
   Usage:   completions-test
   Version: 1.0.0           
 
+  meta1: value1
+  meta2: value2
+  meta3: value3
+
   Description:
 
     Completions test.

command/test/integration/fixtures/help_option_long.out

@@ -2,6 +2,10 @@
   Usage:   completions-test
   Version: 1.0.0           
 
+  meta1: value1
+  meta2: value2
+  meta3: value3
+
   Description:
 
     Completions test.

command/test/integration/fixtures/help_option_short.out

@@ -2,6 +2,10 @@
   Usage:   completions-test
   Version: 1.0.0           
 
+  meta1: value1
+  meta2: value2
+  meta3: value3
+
   Description:
 
     Completions test.