example output not mandatory + add example tests [skip publish]

Author: chenasraf

package.json

@@ -18,7 +18,7 @@
     "clean": "rm -rf build",
     "build": "echo $(pwd); yarn clean && tsc -p tsconfig.build.json && cp package.json README.md src/*.d.ts build",
     "develop": "tsc --watch",
-    "test": "jest && jest-coverage-badges"
+    "test": "jest"
   },
   "devDependencies": {
     "@types/jest": "^26.0.24",

src/assertions.ts

@@ -111,7 +111,7 @@ export function assertOption(option: OptionDef<any, any>, allOptions: OptionDef<
 
 export function assertExample(example: ExampleDef) {
   assertType(example.input, "Example", "Input", { required: true, type: "string" })
-  assertType(example.output, "Example", "Output", { required: true, type: "string" })
+  assertType(example.output, "Example", "Output", { type: "string" })
   assertType(example.description, "Example", "Description", { type: "string" })
 }
 

src/index.ts

@@ -286,8 +286,8 @@ export class Massarg<Options extends OptionsBase = OptionsBase> {
       if (example.description) {
         lines.push(
           ...wrap(this.color(titleColors, example.description), {
-            colorCount: this._help.useColors ? colorCount(titleColors) : 0,
-            firstLineIndent: 2,
+            colorCount: this.colorCount(titleColors),
+            indent: 2,
             printWidth: this._help.printWidth,
           })
         )
@@ -300,22 +300,30 @@ export class Massarg<Options extends OptionsBase = OptionsBase> {
             " "
           ),
           {
-            colorCount: this._help.useColors ? colorCount(highlightColors) : 0,
+            colorCount: this.colorCount(highlightColors),
             firstLineIndent: 2,
+            indent: 3 + this._help.exampleInputPrefix.length,
+            // indent: this.colorCount(normalColors) + 4,
             printWidth: this._help.printWidth,
           }
         )
       )
-      lines.push(
-        ...wrap(
-          [this.color(normalColors, this._help.exampleOutputPrefix), this.color(bodyColors, example.output)].join(" "),
-          {
-            colorCount: this._help.useColors ? colorCount(bodyColors) : 0,
-            firstLineIndent: 2,
-            printWidth: this._help.printWidth,
-          }
+      if (example.output) {
+        lines.push(
+          ...wrap(
+            [this.color(normalColors, this._help.exampleOutputPrefix), this.color(bodyColors, example.output)].join(
+              " "
+            ),
+            {
+              colorCount: this.colorCount(bodyColors),
+              firstLineIndent: 2,
+              indent: 3 + this._help.exampleOutputPrefix.length,
+              // indent: this.colorCount(normalColors) + 4,
+              printWidth: this._help.printWidth,
+            }
+          )
         )
-      )
+      }
       lines.push("")
     }
     return lines
@@ -405,20 +413,18 @@ export class Massarg<Options extends OptionsBase = OptionsBase> {
 
     for (const item of list) {
       const cmdName = this.color(highlightColors, `${item.name}`).padEnd(
-        nameFullSize + (this._help.useColors ? colorCount(highlightColors) : 0) * COLOR_CODE_LEN,
+        nameFullSize + this.colorCount(highlightColors) * COLOR_CODE_LEN,
         " "
       )
       const cmdDescr = this.color(normalColors, item.description ?? "")
 
       for (const line of wrap(cmdName + cmdDescr, {
         indent: nameFullSize + INDENT_LEN,
-        colorCount: this._help.useColors
-          ? colorCount(
-              normalColors,
-              highlightColors,
-              item.additionalColorCount ? new Array({ length: item.additionalColorCount }) : []
-            )
-          : 0,
+        colorCount: this.colorCount(
+          normalColors,
+          highlightColors,
+          item.additionalColorCount ? new Array({ length: item.additionalColorCount }) : []
+        ),
         firstLineIndent: INDENT_LEN,
         printWidth: this._help.printWidth,
       })) {
@@ -532,6 +538,13 @@ export class Massarg<Options extends OptionsBase = OptionsBase> {
     }
     return chalk.reset(output)
   }
+
+  private colorCount(...colors: any[]): number {
+    if (!this._help.useColors) {
+      return 0
+    }
+    return colorCount(...colors)
+  }
 }
 
 export function massarg<T extends OptionsBase = OptionsBase>() {

src/options.d.ts

@@ -254,7 +254,7 @@ export interface ExampleDef {
   input: string
 
   /** The output line - to show the output of whatever `input` is regarding. */
-  output: string
+  output?: string
 
   /** An optional description which will be used as a title. */
   description?: string

tests/examples.test.ts

@@ -0,0 +1,80 @@
+import massarg from "../src"
+
+describe("Examples", () => {
+  test("should parse examples", () => {
+    const helpStr = massarg()
+      .help({ binName: "test", useColors: false })
+      .example({
+        input: "my-cmd --number 10",
+      })
+      .getHelpString()
+      .join("\n")
+
+    expect(helpStr).toBe(
+      "Usage: test [command] [options]" +
+        "\n\n" +
+        "Options:" +
+        "\n\n" +
+        "  --help|-h    Display help information" +
+        "\n\n" +
+        "Examples:" +
+        "\n\n" +
+        "  $ my-cmd --number 10" +
+        "\n"
+    )
+  })
+
+  test("should wrap input properly", () => {
+    const helpStr = massarg()
+      .help({ binName: "test", useColors: false })
+      .example({
+        input: "my-cmd --number 10 --another-number 20 --and-yet-another-number 30 --what-about-another 40",
+      })
+      .getHelpString()
+      .join("\n")
+
+    expect(helpStr).toBe(
+      "Usage: test [command] [options]" +
+        "\n\n" +
+        "Options:" +
+        "\n\n" +
+        "  --help|-h    Display help information" +
+        "\n\n" +
+        "Examples:" +
+        "\n\n" +
+        "  $ my-cmd --number 10 --another-number 20 --and-yet-another-number 30" +
+        "\n" +
+        "    --what-about-another 40" +
+        "\n"
+    )
+  })
+
+  test("should wrap description properly", () => {
+    const helpStr = massarg()
+      .help({ binName: "test", useColors: false })
+      .example({
+        input: "my-cmd --number 10",
+        description:
+          "This is a really long test. Very long text indeed, which should eventually span to more than 1 line, so indentation can be tested.",
+      })
+      .getHelpString()
+      .join("\n")
+
+    expect(helpStr).toBe(
+      "Usage: test [command] [options]" +
+        "\n\n" +
+        "Options:" +
+        "\n\n" +
+        "  --help|-h    Display help information" +
+        "\n\n" +
+        "Examples:" +
+        "\n\n" +
+        "  This is a really long test. Very long text indeed, which should eventually" +
+        "\n" +
+        "  span to more than 1 line, so indentation can be tested." +
+        "\n\n" +
+        "  $ my-cmd --number 10" +
+        "\n"
+    )
+  })
+})