feat(help): add utility to create help screens

packages/ace/example/index.ts

@@ -0,0 +1,63 @@
+/*
+* @adonisjs/ace
+*
+* (c) Harminder Virk <[email protected]>
+*
+* For the full copyright and license information, please view the LICENSE
+* file that was distributed with this source code.
+*/
+
+import { printHelp } from '../src/utils/help'
+import { BaseCommand } from '../src/BaseCommand'
+import { Kernel } from '../src/Kernel'
+
+class Greet extends BaseCommand {
+  public static commandName = 'greet'
+  public static description = 'Greet a user with their name'
+  public static args = [
+    {
+      name: 'name',
+      description: 'The name of the person you want to greet',
+      required: true,
+    },
+    {
+      name: 'age',
+      required: false,
+    },
+  ]
+
+  public static flags = [
+    {
+      name: 'env',
+      description: 'The environment to use to specialize certain commands',
+      type: 'boolean',
+    },
+    {
+      name: 'entrypoint',
+      description: 'The main HTML file that will be requested',
+      type: 'string',
+    },
+    {
+      name: 'fragment',
+      alias: 'f',
+      description: 'HTML fragments loaded on demand',
+      type: 'array',
+    },
+  ]
+}
+
+class MakeController extends BaseCommand {
+  public static commandName = 'make:controller'
+  public static description = 'Create a HTTP controller'
+}
+
+class MakeModel extends BaseCommand {
+  public static commandName = 'make:model'
+  public static description = 'Create database model'
+}
+
+const kernel = new Kernel()
+kernel.flag('env', () => {}, { type: 'string' })
+printHelp([Greet, MakeController, MakeModel], Object.keys(kernel.flags).map((flag) => {
+  return kernel.flags[flag]
+}))

packages/ace/src/utils/help.ts

@@ -9,18 +9,68 @@
 
 import * as padRight from 'pad-right'
 import { green, bold, yellow, dim } from 'kleur'
-import { CommandConstructorContract, CommandArg } from '../Contracts'
 import { sortAndGroupCommands } from './sortAndGroupCommands'
+import { CommandConstructorContract, CommandArg, CommandFlag } from '../Contracts'
+
+/**
+ * Wraps the command arg inside `<>` or `[]` brackets based upon if it's
+ * required or not.
+ */
+function wrapArg (arg: CommandArg): string {
+  return arg.required ? `<${arg.name}>` : `[${arg.name}]`
+}
+
+function getFlagsForDisplay (flags: CommandFlag[]) {
+  return flags.map(({ name, type, alias, description }) => {
+    /**
+     * Display name is the way we want to display a single flag in the
+     * list of flags
+     */
+    const displayName = alias ? `-${alias}, --${name}` : `--${name}`
+
+    /**
+     * The type hints the user about the expectation on the flag type. We only
+     * print the type, when flag is not a boolean.
+     */
+    const displayType = type === 'array' ? 'string[]' : type === 'string' ? 'string' : ''
+
+    return {
+      displayName,
+      displayType,
+      description,
+      width: displayName.length + displayType.length,
+    }
+  })
+}
+
+function getArgsForDisplay (args: CommandArg[]) {
+  return args.map(({ name, description }) => {
+    return {
+      displayName: name,
+      description: description,
+      width: name.length,
+    }
+  })
+}
+
+function getCommandsForDisplay (commands: CommandConstructorContract[]) {
+  return commands.map(({ commandName, description }) => {
+    return { displayName: commandName, description, width: commandName.length }
+  })
+}
 
 /**
  * Prints help for all the commands by sorting them in alphabetical order
  * and grouping them as per their namespace.
  */
-export function printHelp (commands: CommandConstructorContract[]): void {
+export function printHelp (commands: CommandConstructorContract[], flags: CommandFlag[]): void {
+  const flagsList = getFlagsForDisplay(flags)
+  const commandsList = getCommandsForDisplay(commands)
+
   /**
    * Get width of longest command name.
    */
-  const maxWidth = Math.max.apply(Math, commands.map(({ commandName }) => commandName.length))
+  const maxWidth = Math.max.apply(Math, flagsList.concat(commandsList as any).map(({ width }) => width))
 
   /**
    * Sort commands and group them, so that we can print them as per
@@ -38,14 +88,16 @@ export function printHelp (commands: CommandConstructorContract[]): void {
       console.log(`  ${green(padRight(commandName, maxWidth, ' '))}  ${dim(description)}`)
     })
   })
-}
 
-/**
- * Wraps the command arg inside `<>` or `[]` brackets based upon if it's
- * required or not.
- */
-function wrapArg (arg: CommandArg): string {
-  return arg.required ? `<${arg.name}>` : `[${arg.name}]`
+  if (flagsList.length) {
+    console.log('')
+    console.log(bold(yellow('Global Flags')))
+
+    flagsList.forEach(({ displayName, displayType, description = '', width }) => {
+      const whiteSpace = padRight('', maxWidth - width, ' ')
+      console.log(`  ${green(displayName)} ${dim(displayType)} ${whiteSpace}  ${dim(description)}`)
+    })
+  }
 }
 
 /**
@@ -60,34 +112,8 @@ export function printHelpFor (command: CommandConstructorContract): void {
   console.log('')
   console.log(`${yellow('Usage:')} ${command.commandName} ${dim(command.args.map(wrapArg).join(' '))}`)
 
-  const flags = command.flags.map(({ name, type, alias, description }) => {
-    /**
-     * Display name is the way we want to display a single flag in the
-     * list of flags
-     */
-    const displayName = alias ? `-${alias}, --${name}` : `--${name}`
-
-    /**
-     * The type hints the user about the expectation on the flag type. We only
-     * print the type, when flag is not a boolean.
-     */
-    const displayType = type === 'array' ? 'string[]' : type === 'string' ? 'string' : ''
-
-    return {
-      displayName,
-      displayType,
-      description,
-      width: displayName.length + displayType.length,
-    }
-  })
-
-  const args = command.args.map(({ name, description }) => {
-    return {
-      displayName: name,
-      description: description,
-      width: name.length,
-    }
-  })
+  const flags = getFlagsForDisplay(command.flags)
+  const args = getArgsForDisplay(command.args)
 
   /**
    * Getting max width to keep flags and args symmetric