feat: add docopts (#188)

* feat: add docopts

* chore: fix comment

Author: amphro

src/config/config.ts

@@ -496,6 +496,8 @@ export async function toCached(c: Command.Class, plugin?: IPlugin): Promise<Comm
         helpLabel: flag.helpLabel,
         helpGroup: flag.helpGroup,
         allowNo: flag.allowNo,
+        dependsOn: flag.dependsOn,
+        exclusive: flag.exclusive,
       }
     } else {
       flags[name] = {
@@ -511,6 +513,8 @@ export async function toCached(c: Command.Class, plugin?: IPlugin): Promise<Comm
         helpGroup: flag.helpGroup,
         multiple: flag.multiple,
         options: flag.options,
+        dependsOn: flag.dependsOn,
+        exclusive: flag.exclusive,
         // eslint-disable-next-line no-await-in-loop
         default: typeof flag.default === 'function' ? await flag.default({options: {}, flags: {}}) : flag.default,
       }

src/help/command.ts

@@ -5,6 +5,7 @@ import {castArray, compact, sortBy} from '../util'
 import * as Interfaces from '../interfaces'
 import {Example} from '../interfaces/command'
 import {HelpFormatter} from './formatter'
+import {DocOpts} from './docopts'
 
 // Don't use os.EOL because we need to ensure that a string
 // written on any platform, that may use \r\n or \n, will be
@@ -75,7 +76,7 @@ export class CommandHelp extends HelpFormatter {
     return [
       {
         header: this.opts.usageHeader || 'USAGE',
-        generate: ({flags}) => this.usage(flags),
+        generate: () => this.usage(),
       },
       {
         header: 'ARGUMENTS',
@@ -121,15 +122,28 @@ export class CommandHelp extends HelpFormatter {
     ]
   }
 
-  protected usage(flags: Interfaces.Command.Flag[]): string {
+  protected usage(): string {
     const usage = this.command.usage
-    const body = (usage ? castArray(usage) : [this.defaultUsage(flags)])
-    .map(u => `$ ${this.config.bin} ${u}`.trim())
+    const body = (usage ? castArray(usage) : [this.defaultUsage()])
+    .map(u => {
+      const allowedSpacing = this.opts.maxWidth - this.indentSpacing
+      const line = `$ ${this.config.bin} ${u}`.trim()
+      if (line.length > allowedSpacing) {
+        const splitIndex = line.substring(0, allowedSpacing).lastIndexOf(' ')
+        return line.substring(0, splitIndex) + '\n' +
+          this.indent(this.wrap(line.substring(splitIndex), this.indentSpacing * 2))
+      }
+      return this.wrap(line)
+    })
     .join('\n')
-    return this.wrap(body)
+    return body
   }
 
-  protected defaultUsage(_: Interfaces.Command.Flag[]): string {
+  protected defaultUsage(): string {
+    // Docopts by default
+    if (this.opts.docopts === undefined || this.opts.docopts) {
+      return DocOpts.generate(this.command)
+    }
     return compact([
       this.command.id,
       this.command.args.filter(a => !a.hidden).map(a => this.arg(a)).join(' '),

src/help/docopts.ts

@@ -0,0 +1,178 @@
+import {Interfaces} from '..'
+
+type Flag = Interfaces.Command.Flag
+type Flags = Flag[]
+
+/**
+ * DocOpts - See http://docopt.org/.
+ *
+ * flag.exclusive: groups elements when one of the mutually exclusive cases is a required flag: (--apple | --orange)
+ * flag.exclusive: groups elements when none of the mutually exclusive cases is required (optional flags): [--apple | --orange]
+ * flag.dependsOn: specifies that if one element is present, then another one is required: (--apple --orange)
+ *
+ * @example
+ *  {
+ *      name: 'classnames',
+ *      required: true,
+ *      exclusive: ['suitenames']
+ *      ...
+ *  },{
+ *      name: 'suitenames',
+ *      type: 'array'
+ *      required: true
+ *      ...
+ *  }
+ *
+ *  Results in:
+ *      Usage: <%= command.id %> (-n <string> | -s <array>)
+ *
+ * @example
+ *  {
+ *      name: 'classnames',
+ *      ...
+ *      excludes: ['suitenames']
+ *  },{
+ *      name: 'suitenames',
+ *      ...
+ *  }
+ *
+ *  Results in:
+ *      Usage: <%= command.id %> [-n <string> | -s <string>]
+ *
+ * @example
+ *  {
+ *      name: 'classnames',
+ *      ...
+ *      dependsOn: ['suitenames']
+ *  },{
+ *      name: 'suitenames',
+ *      type: 'flag'
+ *      ...
+ *  }
+ *
+ *  Results in:
+ *      Usage: <%= command.id %> (-n <string> -s)
+ *
+ * TODO:
+ *  - Support nesting, eg:
+ *      Usage: my_program (--either-this <and-that> | <or-this>)
+ *      Usage: my_program [(<one-argument> <another-argument>)]
+ *
+ */
+export class DocOpts {
+  private flagMap: {[index: string]: Flag}
+
+  private flagList: Flags
+
+  public constructor(private cmd: Interfaces.Command) {
+    // Create a new map with references to the flags that we can manipulate.
+    this.flagMap = {}
+    this.flagList = Object.entries(cmd.flags || {})
+    .filter(([_, flag]) => !flag.hidden)
+    .map(([name, flag]) => {
+      this.flagMap[name] = flag
+      return flag
+    })
+  }
+
+  public static generate(cmd: Interfaces.Command): string {
+    return new DocOpts(cmd).toString()
+  }
+
+  public toString(): string {
+    const opts = ['<%= command.id %>']
+    if (this.cmd.args) {
+      opts.push(...this.cmd.args?.map(arg => `[${arg.name.toUpperCase()}]`))
+    }
+    try {
+      opts.push(...Object.values(this.groupFlagElements()))
+    } catch (error) {
+      // If there is an error, just return no usage so we don't fail command help.
+      opts.push(...this.flagList.map(flag => {
+        const name = flag.char ? `-${flag.char}` : `--${flag.name}`
+        if (flag.type === 'boolean') return name
+        return `${name}=<value>`
+      }))
+    }
+    return opts.join(' ')
+  }
+
+  private groupFlagElements(): {[index: string]: string} {
+    const elementMap: {[index: string]: string} = {}
+
+    // Generate all doc opt elements for combining
+    // Show required flags first
+    this.generateElements(elementMap, this.flagList.filter(flag => flag.required))
+    // Then show optional flags
+    this.generateElements(elementMap, this.flagList.filter(flag => !flag.required))
+
+    for (const flag of this.flagList) {
+      if (Array.isArray(flag.dependsOn)) {
+        this.combineElementsToFlag(elementMap, flag.name, flag.dependsOn, ' ')
+      }
+
+      if (Array.isArray(flag.exclusive)) {
+        this.combineElementsToFlag(elementMap, flag.name, flag.exclusive, ' | ')
+      }
+    }
+
+    // Since combineElementsToFlag deletes the references in this.flags when it combines
+    // them, this will go through the remaining list of uncombined elements.
+    for (const remainingFlagName of Object.keys(this.flagMap)) {
+      const remainingFlag = this.flagMap[remainingFlagName] || {}
+
+      if (!remainingFlag.required) {
+        elementMap[remainingFlag.name] = `[${elementMap[remainingFlag.name] || ''}]`
+      }
+    }
+    return elementMap
+  }
+
+  private combineElementsToFlag(
+    elementMap: {[index: string]: string},
+    flagName: string,
+    flagNames: string[],
+    unionString: string,
+  ): void {
+    if (!this.flagMap[flagName]) {
+      return
+    }
+    let isRequired = this.flagMap[flagName]?.required
+    if (typeof isRequired !== 'boolean' || !isRequired) {
+      isRequired = flagNames.reduce(
+        (required: boolean, toCombine) => required || this.flagMap[toCombine]?.required || false,
+        false,
+      )
+    }
+
+    for (const toCombine of flagNames) {
+      elementMap[flagName] = `${elementMap[flagName] || ''}${unionString}${elementMap[toCombine] || ''}`
+      // We handled this flag, don't handle it again
+      delete elementMap[toCombine]
+      delete this.flagMap[toCombine]
+    }
+    if (isRequired) {
+      elementMap[flagName] = `(${elementMap[flagName] || ''})`
+    } else {
+      elementMap[flagName] = `[${elementMap[flagName] || ''}]`
+    }
+    // We handled this flag, don't handle it again
+    delete this.flagMap[flagName]
+  }
+
+  private generateElements(elementMap: {[index: string]: string} = {}, flagGroups: Flags): string[] {
+    const elementStrs = []
+    for (const flag of flagGroups) {
+      let type = ''
+      // 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>'
+      }
+      const element = `${flagName}${type}`
+      elementMap[flag.name] = element
+      elementStrs.push(element)
+    }
+    return elementStrs
+  }
+}

src/interfaces/help.ts

@@ -28,4 +28,8 @@ export interface HelpOptions {
    * http://www.gnu.org/software/help2man/#--help-recommendations
    */
   usageHeader?: string;
+  /**
+   * Use docopts as the usage. Defaults to true.
+   */
+  docopts?: boolean;
 }

src/interfaces/parser.ts

@@ -109,6 +109,8 @@ export type FlagProps = {
   helpGroup?: string;
   hidden?: boolean;
   required?: boolean;
+  dependsOn?: string[];
+  exclusive?: string[];
 }
 
 export type BooleanFlagProps = FlagProps & {
@@ -124,8 +126,6 @@ export type OptionFlagProps = FlagProps & {
 }
 
 export type FlagBase<T, I> = FlagProps & {
-  dependsOn?: string[];
-  exclusive?: string[];
   exactlyOne?: string[];
   /**
    * also accept an environment variable as input