feat(help): Added custom help feature (#47)

Allow user to define a custom help for both global and commands (fixes
#30)
Also fixes #14.

README.md

@@ -303,6 +303,49 @@ Help can be displayed using `-h` or `--help` options, or with the default `help`
  <img src="https://github.com/mattallty/Caporal.js/raw/master/assets/colors.png" wdith="600">
 </p>
 
+## Custom help
+
+You can add some custom help to the whole program or to specific commands using `.help()`.
+
+
+### Custom help for the whole program
+
+```javascript
+#!/usr/bin/env node
+const prog = require('caporal');
+prog
+  .version('1.0.0')
+  .help('my global help') // here our custom help for the whole program
+  .command('order pizza')
+  .action(function(args, options) {
+
+  });
+
+prog.parse(process.argv);
+```
+
+### Custom help for specific commands
+
+```javascript
+#!/usr/bin/env node
+const prog = require('caporal');
+prog
+  .version('1.0.0')
+  // first command
+  .command('order')
+  .help('my help for the order command') // here our custom help for the `order` command
+  .action(function(args, options) {
+
+  })
+  // second command
+  .command('cancel')
+  .help('my help for the cancel command') // here our custom help for the `cancel` command
+  .action(function(args, options) {
+
+  })
+
+prog.parse(process.argv);
+```
 
 ## Typo suggestions
 

examples/pizza/pizza.js

@@ -6,7 +6,9 @@ const prog = require('../..');
 prog
   .version('1.0.0')
   // the "order" command
+  .help(`My Custom help !!`)
   .command('order', 'Order a pizza')
+  .help(`My Custom help about the order command !!`)
   .alias('give-it-to-me')
   // <kind> will be auto-magicaly autocompleted by providing the user with 3 choices
   .argument('<kind>', 'Kind of pizza', ["margherita", "hawaiian", "fredo"])

lib/command.js

@@ -37,6 +37,16 @@ class Command extends GetterSetter {
   }
 
 
+  /**
+   * Add help for the current command
+   *
+   * @param {String} help - Help string
+   * @returns {Command}
+   */
+  help(help) {
+    this._program._helper._addCustomHelp(help, this);
+    return this;
+  }
 
   /**
    * @private

lib/help.js

@@ -4,13 +4,28 @@ const Table = require('cli-table2');
 const chalk = require('chalk');
 const colorize = require('./colorful').colorize;
 
+/**
+ * @private
+ */
 class Help {
 
   constructor(program) {
     this._program = program;
+    this._customHelp = {};
   }
 
-  display(command) {
+  /**
+   * Add a custom help for the whole program or a specific command
+   *
+   * @param {String} help - Help text
+   * @param {Command|null} command - Command concerned or null for program help
+   * @private
+   */
+  _addCustomHelp(help, command) {
+    this._customHelp[command ? command._name : '_program'] = help;
+  }
+
+  get(command) {
 
     if (!command && this._program._commands.length === 1) {
       command = this._program._commands[0];
@@ -20,15 +35,19 @@ class Help {
     let help = `
    ${chalk.cyan(this._program.name() || this._program.bin())} ${chalk.dim(this._program.version())} ${description}
      
-   ${this._getUsage(command)} `;
+   ${this._getUsage(command)}`;
 
     if (!command && this._program._commands.length > 1) {
       help += "\n\n   " + this._getCommands();
     }
 
     help += "\n\n   " + this._getGlobalOptions();
 
-    return console.log(help + "\n");
+    if (this._customHelp['_program']) {
+      help += "\n\n   " + chalk.bold('MORE INFO') + "\n\n     " + this._customHelp['_program'];
+    }
+
+    return help + "\n";
   }
 
   _getCommands() {
@@ -53,6 +72,10 @@ class Help {
     const options = cmd.options();
     let help = (cmd.name() ? cmd.name() + ' ' : '') + args.map(a => a.synopsis()).join(' ');
 
+    if (this._customHelp[cmd._name]) {
+      help += `\n\n     ${this._customHelp[cmd._name]}`;
+    }
+
     if (args.length) {
       help += `\n\n   ${chalk.bold('ARGUMENTS')}\n\n`;
       const argsTable = this._getSimpleTable();

lib/program.js

@@ -15,7 +15,7 @@ class Program extends GetterSetter {
   constructor() {
     super();
     this._commands = [];
-    this._help = new Help(this);
+    this._helper = new Help(this);
     this.version = this.makeGetterSetter('version');
     this.name = this.makeGetterSetter('name');
     this.description = this.makeGetterSetter('description');
@@ -31,9 +31,22 @@ class Program extends GetterSetter {
   /**
    * @private
    */
-  help(cmdStr) {
+  _help(cmdStr) {
     const cmd = this._commands.filter(c => (c.name() === cmdStr || c.getAlias() === cmdStr))[0];
-    this._help.display(cmd);
+    const help = this._helper.get(cmd);
+    console.log(help);
+    return help;
+  }
+
+  /**
+   * Add a global help for your program
+   *
+   * @param {String} help - Help string
+   * @returns {Program}
+   */
+  help(help) {
+    this._helper._addCustomHelp(help);
+    return this;
   }
 
   /**
@@ -87,7 +100,7 @@ class Program extends GetterSetter {
   _run(args, options) {
 
     if (args[0] === 'help') {
-      this.help(args.slice(1).join(' '));
+      this._help(args.slice(1).join(' '));
       return process.exit(0);
     }
 
@@ -115,7 +128,7 @@ class Program extends GetterSetter {
     }
 
     if (!cmd || options.help || options.h) {
-      this.help();
+      this._help(args.join(' '));
       return process.exit(0);
     }