feat: added option to specify example flag value in docopts

src/help/command.ts

@@ -166,12 +166,11 @@ export class CommandHelp extends HelpFormatter {
     }
 
     if (flag.type === 'option') {
-      let value = flag.helpValue || (this.opts.showFlagNameInTitle ? flag.name : '<value>')
-      if (!flag.helpValue && flag.options) {
-        value = showOptions || this.opts.showFlagOptionsInTitle ? `${flag.options.join('|')}` : '<option>'
-      }
-
-      if (flag.multiple) value += '...'
+      let value = DocOpts.formatUsageType(
+        flag,
+        this.opts.showFlagNameInTitle ?? false,
+        this.opts.showFlagOptionsInTitle ?? showOptions,
+      )
       if (!value.includes('|')) value = chalk.underline(value)
       label += `=${value}`
     }

src/help/docopts.ts

@@ -72,6 +72,26 @@ export class DocOpts {
       })
   }
 
+  public static formatUsageType(flag: Command.Flag.Any, showFlagName: boolean, showOptions: boolean): string {
+    if (flag.type !== 'option') return ''
+
+    let helpValues: string[]
+    if (flag.helpValue) {
+      // if there is a given helpValue, use it
+      helpValues = typeof flag.helpValue === 'string' ? [flag.helpValue] : flag.helpValue
+    } else if (flag.options) {
+      // if there are options, show them if wanted
+      helpValues = [showOptions ? flag.options.join('|') : '<option>']
+    } else if (showFlagName) {
+      helpValues = [flag.name]
+    } else {
+      // default to <value>
+      helpValues = ['<value>']
+    }
+
+    return helpValues.map((v) => `${v}${flag.multiple ? '...' : ''}`).join(' ')
+  }
+
   public static generate(cmd: Command.Loadable): string {
     return new DocOpts(cmd).toString()
   }
@@ -96,7 +116,7 @@ export class DocOpts {
         ...this.flagList.map((flag) => {
           const name = flag.char ? `-${flag.char}` : `--${flag.name}`
           if (flag.type === 'boolean') return name
-          return `${name}=<value>`
+          return `${name}=${DocOpts.formatUsageType(flag, false, true)}`
         }),
       )
     }
@@ -142,7 +162,7 @@ export class DocOpts {
       // not all flags have short names
       const flagName = flag.char ? `-${flag.char}` : `--${flag.name}`
       if (flag.type === 'option') {
-        type = flag.options ? ` ${flag.options.join('|')}` : ' <value>'
+        type = ` ${DocOpts.formatUsageType(flag, false, true)}`
       }
 
       const element = `${flagName}${type}`

src/interfaces/parser.ts

@@ -206,7 +206,7 @@ export type BooleanFlagProps = FlagProps & {
 
 export type OptionFlagProps = FlagProps & {
   type: 'option'
-  helpValue?: string
+  helpValue?: string | string[]
   options?: readonly string[]
   multiple?: boolean
   /**
@@ -295,10 +295,10 @@ type FlagReturnType<T, R extends ReturnTypeSwitches> = R['requiredOrDefaulted']
       : T[]
     : T
   : R['multiple'] extends true
-  ? [T] extends [Array<unknown>]
-    ? T | undefined
-    : T[] | undefined
-  : T | undefined
+    ? [T] extends [Array<unknown>]
+      ? T | undefined
+      : T[] | undefined
+    : T | undefined
 
 /**
  * FlagDefinition types a function that takes `options` and returns an OptionFlag<T>.

test/help/docopts.test.ts

@@ -265,4 +265,41 @@ describe('doc opts', () => {
     } as any)
     expect(usage).to.contain(' (-s <value> -f <value>)')
   })
+
+  it('is uses helpValues as expected', () => {
+    const usage = DocOpts.generate({
+      flags: {
+        testFlag: Flags.url({
+          name: 'testFlag',
+          description: 'test',
+          char: 's',
+          required: true,
+          helpValue: ['<test1>', '<test2>'],
+          multiple: true,
+        }),
+        testFlag2: Flags.string({
+          name: 'testFlag2',
+          description: 'test',
+          char: 'f',
+          required: true,
+          helpValue: '<test3>',
+        }),
+        testFlag3: Flags.string({
+          name: 'testFlag3',
+          description: 'test',
+          char: 'g',
+          required: true,
+          multiple: true,
+        }),
+        testFlag4: Flags.string({
+          name: 'testFlag4',
+          description: 'test',
+          char: 'p',
+          required: true,
+          options: ['option1', 'option2'],
+        }),
+      },
+    } as any)
+    expect(usage).to.contain('-s <test1>... <test2>... -f <test3> -g <value>... -p option1|option2')
+  })
 })

test/help/format-command.test.ts

@@ -339,7 +339,7 @@ FLAGS
                      <options: a|b|c>`)
     })
 
-    it('should output flag enum with helpValue', async () => {
+    it('should output flag enum with string helpValue', async () => {
       const cmd = await makeLoadable(
         makeCommandClass({
           id: 'apps:create',
@@ -360,6 +360,69 @@ FLAGS
   --myenum=a|b|c`)
     })
 
+    it('should output flag enum with array helpValue', async () => {
+      const cmd = await makeLoadable(
+        makeCommandClass({
+          id: 'apps:create',
+          flags: {
+            myenum: flags.string({
+              options: myEnumValues,
+              helpValue: myEnumValues,
+            }),
+          },
+        }),
+      )
+
+      const output = help.formatCommand(cmd)
+      expect(output).to.equal(`USAGE
+  $ oclif apps:create [--myenum a b c]
+
+FLAGS
+  --myenum=a b c`)
+    })
+
+    it('should output string helpValue in usage string', async () => {
+      const cmd = await makeLoadable(
+        makeCommandClass({
+          id: 'apps:create',
+          flags: {
+            files: flags.string({
+              helpValue: '<input-json>|<input-xml>',
+              multiple: true,
+            }),
+          },
+        }),
+      )
+
+      const output = help.formatCommand(cmd)
+      expect(output).to.equal(`USAGE
+  $ oclif apps:create [--files <input-json>|<input-xml>...]
+
+FLAGS
+  --files=<input-json>|<input-xml>...`)
+    })
+
+    it('should output array helpValue in usage string', async () => {
+      const cmd = await makeLoadable(
+        makeCommandClass({
+          id: 'apps:create',
+          flags: {
+            files: flags.string({
+              helpValue: ['<input-json>', '<input-xml>'],
+              multiple: true,
+            }),
+          },
+        }),
+      )
+
+      const output = help.formatCommand(cmd)
+      expect(output).to.equal(`USAGE
+  $ oclif apps:create [--files <input-json>... <input-xml>...]
+
+FLAGS
+  --files=<input-json>... <input-xml>...`)
+    })
+
     it('should output with default flag options', async () => {
       const cmd = await makeLoadable(
         makeCommandClass({