Add support for "local" and global help:header, help:body and help:footer

examples/help-global-listeners

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+// const program = require('commander'); // (normal include)
+const program = require('../'); // include commander in git clone of commander repo
+const { commanderGlobalEmitter } = require('../')
+
+commanderGlobalEmitter
+  .on('help:header', () => {
+    console.log('Global Header\n');
+  })
+  .on('help:body', (instance) => {
+    console.log('++++++global++++++');
+    console.log(instance.helpInformation().replace(/\n$/, '\n++++++global++++++\n'));
+  })
+  .on('help:footer', () => {
+    console.log(`The End.`);
+  })
+
+
+program
+  .version('0.0.1')
+  .option('-b, --bar', 'enable some bar')
+
+program
+  .on('help:header', () => {
+    console.log('Custom Header\n');
+  })
+  .on('help:body', (instance) => {
+    console.log('------local------');
+    console.log(instance.helpInformation().replace(/\n$/, '\n------local------\n'));
+  })
+  .on('help:footer', () => {
+    console.log(`Commander - ${new Date().getFullYear()}`);
+  })
+  .command('foo')
+  .action(() => {})
+
+program  
+  .parse(process.argv);
+
+/**
+ * examples/help-global-listeners -h
+ * 
+ * Should display both global and "local" emitter messages
+ */
+
+/**
+ * examples/help-global-listeners foo -h
+ * 
+ * Should display only global emitter messages
+ */

examples/help-listeners

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+// const program = require('commander'); // (normal include)
+const program = require('../'); // include commander in git clone of commander repo
+
+program
+  .version('0.0.1')
+  .option('-b, --bar', 'enable some bar')
+  .on('help:header', () => {
+    console.log('Custom Header\n');
+  })
+  .on('help:body', (instance) => {
+    console.log('------------');
+    console.log(instance.helpInformation().replace(/\n$/, '\n------------\n'));
+  })
+  .on('help:footer', () => {
+    console.log(`Commander - ${new Date().getFullYear()}`);
+  })
+  .parse(process.argv);
+
+  if (!program.args.length) program.help();

index.js

@@ -6,6 +6,7 @@ const EventEmitter = require('events').EventEmitter;
 const spawn = require('child_process').spawn;
 const path = require('path');
 const fs = require('fs');
+const globalEventEmitter = new EventEmitter();
 
 // @ts-check
 
@@ -128,6 +129,9 @@ class Command extends EventEmitter {
     this._helpCommandName = 'help';
     this._helpCommandnameAndArgs = 'help [command]';
     this._helpCommandDescription = 'display help for command';
+    this._helpHeader = 'help:header';
+    this._helpBody = 'help:body';
+    this._helpFooter = 'help:footer';
   }
 
   /**
@@ -1530,12 +1534,23 @@ class Command extends EventEmitter {
         return passthru;
       };
     }
+    globalEventEmitter.emit(this._helpHeader, this);
+    this.emit(this._helpHeader, this);
     const cbOutput = cb(this.helpInformation());
     if (typeof cbOutput !== 'string' && !Buffer.isBuffer(cbOutput)) {
       throw new Error('outputHelp callback must return a string or a Buffer');
     }
-    process.stdout.write(cbOutput);
-    this.emit(this._helpLongFlag);
+    const globalBodyListeners = globalEventEmitter.listeners(this._helpBody);
+    const bodyListeners = this.listeners(this._helpBody);
+    if (bodyListeners.length === 0 && globalBodyListeners.length === 0) {
+      process.stdout.write(cbOutput);
+    } else {
+      globalEventEmitter.emit(this._helpBody, this);
+      this.emit(this._helpBody, this);
+    }
+    this.emit(this._helpLongFlag); // Leave .on('--help') in for compatibility
+    this.emit(this._helpFooter, this);
+    globalEventEmitter.emit(this._helpFooter, this);
   };
 
   /**
@@ -1604,6 +1619,12 @@ exports.Command = Command;
 exports.Option = Option;
 exports.CommanderError = CommanderError;
 
+/**
+ * Expose Global Emiter
+ */
+
+exports.commanderGlobalEmitter = globalEventEmitter;
+
 /**
  * Camel-case the given `flag`
  *

tests/command.helpGlobalListener.test.js

@@ -0,0 +1,124 @@
+const commander = require('../');
+const { commanderGlobalEmitter } = require('../');
+
+jest.spyOn(global.console, 'log').mockImplementation();
+
+// Testing help listeners, both "local" and global
+
+// Avoid doing many full format tests as will be broken by any layout changes!
+test('when listening for the global help:body the default help command should be overridden', () => {
+  const program = new commander.Command();
+
+  commanderGlobalEmitter
+    .on('help:body', (instance) => {
+      console.log(`------------
+${instance.helpInformation().replace(/\n$/, '\n------------\n')}`);
+    });
+
+  program
+    .command('my-command <file>');
+  const expectedHelpInformation =
+`------------
+Usage: test [options] [command]
+
+Options:
+  -h, --help         display help for command
+
+Commands:
+  my-command <file>
+  help [command]     display help for command
+------------
+`;
+
+  program.name('test');
+  program.outputHelp();
+  expect(global.console.log).toHaveBeenCalledWith(expectedHelpInformation);
+});
+
+test('when listening for the global help:header the listener should be called correctly', () => {
+  const program = new commander.Command();
+  const listenerCall = jest.fn();
+
+  commanderGlobalEmitter
+    .on('help:header', listenerCall);
+
+  program
+    .command('my-command <file>');
+
+  program.outputHelp();
+  expect(listenerCall).toHaveBeenCalledTimes(1);
+});
+
+test('when listening for the global help:footer the listener should be called correctly', () => {
+  const program = new commander.Command();
+  const listenerCall = jest.fn();
+
+  commanderGlobalEmitter
+    .on('help:footer', listenerCall);
+
+  program
+    .command('my-command <file>');
+
+  program.outputHelp();
+  expect(listenerCall).toHaveBeenCalledTimes(1);
+});
+
+test('when listening for global help:header, help:body and help:footer they should be called in the correct order', () => {
+  const program = new commander.Command();
+  const callOrder = [];
+
+  commanderGlobalEmitter
+    .on('help:footer', () => {
+      callOrder.push('help:footer');
+    })
+    .on('help:header', () => {
+      callOrder.push('help:header');
+    })
+    .on('help:body', () => {
+      callOrder.push('help:body');
+    });
+
+  program
+    .command('my-command <file>');
+
+  program.outputHelp();
+  expect(callOrder[0]).toBe('help:header');
+  expect(callOrder[1]).toBe('help:body');
+  expect(callOrder[2]).toBe('help:footer');
+});
+
+test('when listening for local and global help:header, help:body and help:footer they should be called in the correct order', () => {
+  const program = new commander.Command();
+  const callOrder = [];
+
+  commanderGlobalEmitter
+    .on('help:footer', () => {
+      callOrder.push('global:help:footer');
+    })
+    .on('help:header', () => {
+      callOrder.push('global:help:header');
+    })
+    .on('help:body', () => {
+      callOrder.push('global:help:body');
+    });
+
+  program
+    .on('help:footer', () => {
+      callOrder.push('help:footer');
+    })
+    .on('help:header', () => {
+      callOrder.push('help:header');
+    })
+    .on('help:body', () => {
+      callOrder.push('help:body');
+    })
+    .command('my-command <file>');
+
+  program.outputHelp();
+  expect(callOrder[0]).toBe('global:help:header');
+  expect(callOrder[1]).toBe('help:header');
+  expect(callOrder[2]).toBe('global:help:body');
+  expect(callOrder[3]).toBe('help:body');
+  expect(callOrder[4]).toBe('help:footer');
+  expect(callOrder[5]).toBe('global:help:footer');
+});

tests/command.helpListener.test.js

@@ -0,0 +1,77 @@
+const commander = require('../');
+
+jest.spyOn(global.console, 'log').mockImplementation();
+
+// Testing help listeners, both "local" and global
+
+// Avoid doing many full format tests as will be broken by any layout changes!
+test('when listening for the help:body the default help command should be overridden', () => {
+  const program = new commander.Command();
+  program
+    .on('help:body', (instance) => {
+      console.log(`------------
+${instance.helpInformation().replace(/\n$/, '\n------------\n')}`);
+    })
+    .command('my-command <file>');
+  const expectedHelpInformation =
+`------------
+Usage: test [options] [command]
+
+Options:
+  -h, --help         display help for command
+
+Commands:
+  my-command <file>
+  help [command]     display help for command
+------------
+`;
+
+  program.name('test');
+  program.outputHelp();
+  expect(global.console.log).toHaveBeenCalledWith(expectedHelpInformation);
+});
+
+test('when listening for the help:header the listener should be called correctly', () => {
+  const program = new commander.Command();
+  const listenerCall = jest.fn();
+  program
+    .on('help:header', listenerCall)
+    .on('help:body', () => {}) // to prevent printing to console
+    .command('my-command <file>');
+
+  program.outputHelp();
+  expect(listenerCall).toHaveBeenCalledTimes(1);
+});
+
+test('when listening for the help:footer the listener should be called correctly', () => {
+  const program = new commander.Command();
+  const listenerCall = jest.fn();
+  program
+    .on('help:footer', listenerCall)
+    .on('help:body', () => {}) // to prevent printing to console
+    .command('my-command <file>');
+
+  program.outputHelp();
+  expect(listenerCall).toHaveBeenCalledTimes(1);
+});
+
+test('when listening for help:header, help:body and help:footer they should be called in the correct order', () => {
+  const program = new commander.Command();
+  const callOrder = [];
+  program
+    .on('help:footer', () => {
+      callOrder.push('help:footer');
+    })
+    .on('help:header', () => {
+      callOrder.push('help:header');
+    })
+    .on('help:body', () => {
+      callOrder.push('help:body');
+    })
+    .command('my-command <file>');
+
+  program.outputHelp();
+  expect(callOrder[0]).toBe('help:header');
+  expect(callOrder[1]).toBe('help:body');
+  expect(callOrder[2]).toBe('help:footer');
+});

typings/commander-tests.ts

@@ -220,3 +220,8 @@ const myProgram = new MyCommand();
 myProgram.myFunction();
 const mySub = myProgram.command('sub');
 mySub.myFunction();
+
+// globalEventEmitter
+const onGlobal: commander.CommanderGlobalEmitter = commander.commanderGlobalEmitter.on('help:body', () => {
+  // do nothing.
+});

typings/index.d.ts

@@ -27,6 +27,15 @@ declare namespace commander {
     from: 'node' | 'electron' | 'user';
   }
 
+  // (string & {}) is sort of a hack so we able to show the string types autocompletion
+  // as well as allow any string to be used
+  export type Event =
+  | 'help:header'
+  | 'help:body'
+  | 'help:footer'
+  | (string & {})
+  | symbol
+
   interface Command {
     [key: string]: any; // options as properties
 
@@ -353,7 +362,7 @@ declare namespace commander {
      *         console.log('See web site for more information.');
      *     });
      */
-    on(event: string | symbol, listener: (...args: any[]) => void): this;
+    on(event: Event, listener: (...args: any[]) => void): this;
   }
   type CommandConstructor = new (name?: string) => Command;
 
@@ -371,13 +380,26 @@ declare namespace commander {
     unknown: string[];
   }
 
+  interface CommanderGlobalEmitter {
+    /**
+     * Add a listener (callback) for when events occur. (Implemented using EventEmitter.)
+     *
+     * @example
+     *     program
+     *       .on('help:body', () -> {
+     *         console.log('See web site for more information.');
+     *     });
+     */
+    on(event: Event, listener: (...args: any[]) => void): this;
+  }
+
   interface CommanderStatic extends Command {
     program: Command;
+    commanderGlobalEmitter: CommanderGlobalEmitter;
     Command: CommandConstructor;
     Option: OptionConstructor;
     CommanderError: CommanderErrorConstructor;
   }
-
 }
 
 // Declaring namespace AND global