From 713db77d5744a9274ee3812400243ffaae3b7abc Mon Sep 17 00:00:00 2001 From: Jared Petersen Date: Fri, 31 Aug 2018 15:05:24 -0700 Subject: [PATCH] Standardize help output (#853) * Removed newline before and after help output * Updated English documentation and examples * Unindented help output * Fixed newline and indentation for missing command error * Updated REAME examples in English and Chinese and fixed example indentation * Removed newlines surrounding EACCESS error message --- Readme.md | 50 +++++++++++++--------------- Readme_zh-CN.md | 38 ++++++++++----------- examples/custom-help | 6 ++-- index.js | 22 ++++++------ test/test.command.help.js | 4 +-- test/test.command.helpInformation.js | 15 ++++----- test/test.command.name.js | 2 +- test/test.command.nohelp.js | 8 ++--- 8 files changed, 67 insertions(+), 78 deletions(-) diff --git a/Readme.md b/Readme.md index 5897d371a..8484c47a8 100644 --- a/Readme.md +++ b/Readme.md @@ -45,7 +45,7 @@ console.log(' - %s cheese', program.cheese); Short flags may be passed as a single arg, for example `-abc` is equivalent to `-a -b -c`. Multi-word options such as "--template-engine" are camel-cased, becoming `program.templateEngine` etc. -Note that multi-word options starting with `--no` prefix negate the boolean value of the following word. For example, `--no-sauce` sets the value of `program.sauce` to false. +Note that multi-word options starting with `--no` prefix negate the boolean value of the following word. For example, `--no-sauce` sets the value of `program.sauce` to false. ```js #!/usr/bin/env node @@ -153,7 +153,7 @@ program .option('-s --size ', 'Pizza size', /^(large|medium|small)$/i, 'medium') .option('-d --drink [drink]', 'Drink', /^(coke|pepsi|izze)$/i) .parse(process.argv); - + console.log(' size: %j', program.size); console.log(' drink: %j', program.drink); ``` @@ -248,22 +248,20 @@ You can enable `--harmony` option in two ways: The help information is auto-generated based on the information commander already knows about your program, so the following `--help` info is for free: ``` - $ ./examples/pizza --help - - Usage: pizza [options] +$ ./examples/pizza --help +Usage: pizza [options] - An application for pizzas ordering +An application for pizzas ordering - Options: - - -h, --help output usage information - -V, --version output the version number - -p, --peppers Add peppers - -P, --pineapple Add pineapple - -b, --bbq Add bbq sauce - -c, --cheese Add the specified type of cheese [marble] - -C, --no-cheese You do not want any cheese +Options: + -h, --help output usage information + -V, --version output the version number + -p, --peppers Add peppers + -P, --pineapple Add pineapple + -b, --bbq Add bbq sauce + -c, --cheese Add the specified type of cheese [marble] + -C, --no-cheese You do not want any cheese ``` ## Custom help @@ -271,7 +269,7 @@ You can enable `--harmony` option in two ways: You can display arbitrary `-h, --help` information by listening for "--help". Commander will automatically exit once you are done so that the remainder of your program - does not execute causing undesired behaviours, for example + does not execute causing undesired behaviors, for example in the following executable "stuff" will not output when `--help` is used. @@ -294,11 +292,11 @@ program // node's emit() is immediate program.on('--help', function(){ - console.log(' Examples:'); - console.log(''); - console.log(' $ custom-help --help'); - console.log(' $ custom-help -h'); + console.log('') + console.log('Examples:'); console.log(''); + console.log(' $ custom-help --help'); + console.log(' $ custom-help -h'); }); program.parse(process.argv); @@ -309,7 +307,6 @@ console.log('stuff'); Yields the following help output when `node script-name.js -h` or `node script-name.js --help` are run: ``` - Usage: custom-help [options] Options: @@ -324,7 +321,6 @@ Examples: $ custom-help --help $ custom-help -h - ``` ## .outputHelp(cb) @@ -402,11 +398,11 @@ program .action(function(cmd, options){ console.log('exec "%s" using %s mode', cmd, options.exec_mode); }).on('--help', function() { - console.log(' Examples:'); - console.log(); - console.log(' $ deploy exec sequential'); - console.log(' $ deploy exec async'); - console.log(); + console.log(''); + console.log('Examples:'); + console.log(''); + console.log(' $ deploy exec sequential'); + console.log(' $ deploy exec async'); }); program diff --git a/Readme_zh-CN.md b/Readme_zh-CN.md index 87c3a87d2..d6be09786 100644 --- a/Readme_zh-CN.md +++ b/Readme_zh-CN.md @@ -186,22 +186,20 @@ Commander 将会尝试在入口脚本（例如 `./examples/pm`）的目录中搜 帮助信息是 commander 基于你的程序自动生成的，下面是 `--help` 生成的帮助信息： ``` - $ ./examples/pizza --help +$ ./examples/pizza --help +Usage: pizza [options] - Usage: pizza [options] +An application for pizzas ordering - An application for pizzas ordering - - Options: - - -h, --help output usage information - -V, --version output the version number - -p, --peppers Add peppers - -P, --pineapple Add pineapple - -b, --bbq Add bbq sauce - -c, --cheese Add the specified type of cheese [marble] - -C, --no-cheese You do not want any cheese +Options: + -h, --help output usage information + -V, --version output the version number + -p, --peppers Add peppers + -P, --pineapple Add pineapple + -b, --bbq Add bbq sauce + -c, --cheese Add the specified type of cheese [marble] + -C, --no-cheese You do not want any cheese ``` ## 自定义帮助 @@ -227,11 +225,11 @@ program // node's emit() is immediate program.on('--help', function(){ + console.log(''); console.log(' Examples:'); console.log(''); console.log(' $ custom-help --help'); console.log(' $ custom-help -h'); - console.log(''); }); program.parse(process.argv); @@ -242,7 +240,6 @@ console.log('stuff'); 下列帮助信息是运行 `node script-name.js -h` or `node script-name.js --help` 时输出的: ``` - Usage: custom-help [options] Options: @@ -257,7 +254,6 @@ Examples: $ custom-help --help $ custom-help -h - ``` ## .outputHelp(cb) @@ -318,11 +314,11 @@ program .action(function(cmd, options){ console.log('exec "%s" using %s mode', cmd, options.exec_mode); }).on('--help', function() { - console.log(' Examples:'); - console.log(); - console.log(' $ deploy exec sequential'); - console.log(' $ deploy exec async'); - console.log(); + console.log(''); + console.log('Examples:'); + console.log(''); + console.log(' $ deploy exec sequential'); + console.log(' $ deploy exec async'); }); program diff --git a/examples/custom-help b/examples/custom-help index 039e5103d..7260d9cb0 100755 --- a/examples/custom-help +++ b/examples/custom-help @@ -16,11 +16,11 @@ program // node's emit() is immediate program.on('--help', function(){ - console.log(' Examples:'); console.log(''); - console.log(' $ custom-help --help'); - console.log(' $ custom-help -h'); + console.log('Examples:'); console.log(''); + console.log(' $ custom-help --help'); + console.log(' $ custom-help -h'); }); program.parse(process.argv); diff --git a/index.js b/index.js index 22c15adac..8e296691c 100644 --- a/index.js +++ b/index.js @@ -580,9 +580,9 @@ Command.prototype.executeSubCommand = function(argv, args, unknown) { proc.on('close', process.exit.bind(process)); proc.on('error', function(err) { if (err.code === 'ENOENT') { - console.error('\n %s(1) does not exist, try --help\n', bin); + console.error('%s(1) does not exist, try --help', bin); } else if (err.code === 'EACCES') { - console.error('\n %s(1) not executable. try chmod or run with root\n', bin); + console.error('%s(1) not executable. try chmod or run with root', bin); } process.exit(1); }); @@ -1072,12 +1072,12 @@ Command.prototype.commandHelp = function() { var width = this.padWidth(); return [ - ' Commands:', + 'Commands:', '', commands.map(function(cmd) { var desc = cmd[1] ? ' ' + cmd[1] : ''; return (desc ? pad(cmd[0], width) : cmd[0]) + desc; - }).join('\n').replace(/^/gm, ' '), + }).join('\n').replace(/^/gm, ' '), '' ].join('\n'); }; @@ -1093,17 +1093,17 @@ Command.prototype.helpInformation = function() { var desc = []; if (this._description) { desc = [ - ' ' + this._description, + this._description, '' ]; var argsDescription = this._argsDescription; if (argsDescription && this._args.length) { var width = this.padWidth(); - desc.push(' Arguments:'); + desc.push('Arguments:'); desc.push(''); this._args.forEach(function(arg) { - desc.push(' ' + pad(arg.name, width) + ' ' + argsDescription[arg.name]); + desc.push(' ' + pad(arg.name, width) + ' ' + argsDescription[arg.name]); }); desc.push(''); } @@ -1114,8 +1114,7 @@ Command.prototype.helpInformation = function() { cmdName = cmdName + '|' + this._alias; } var usage = [ - '', - ' Usage: ' + cmdName + ' ' + this.usage(), + 'Usage: ' + cmdName + ' ' + this.usage(), '' ]; @@ -1124,9 +1123,9 @@ Command.prototype.helpInformation = function() { if (commandHelp) cmds = [commandHelp]; var options = [ - ' Options:', + 'Options:', '', - '' + this.optionHelp().replace(/^/gm, ' '), + '' + this.optionHelp().replace(/^/gm, ' '), '' ]; @@ -1134,7 +1133,6 @@ Command.prototype.helpInformation = function() { .concat(desc) .concat(options) .concat(cmds) - .concat(['']) .join('\n'); }; diff --git a/test/test.command.help.js b/test/test.command.help.js index 412cb3996..71cc7ccf4 100644 --- a/test/test.command.help.js +++ b/test/test.command.help.js @@ -5,8 +5,8 @@ var program = require('../') program.command('bare'); -program.commandHelp().should.equal(' Commands:\n\n bare\n'); +program.commandHelp().should.equal('Commands:\n\n bare\n'); program.command('mycommand [options]'); -program.commandHelp().should.equal(' Commands:\n\n bare\n mycommand [options]\n'); \ No newline at end of file +program.commandHelp().should.equal('Commands:\n\n bare\n mycommand [options]\n'); diff --git a/test/test.command.helpInformation.js b/test/test.command.helpInformation.js index 0c8f3877e..184b74c1a 100644 --- a/test/test.command.helpInformation.js +++ b/test/test.command.helpInformation.js @@ -7,18 +7,17 @@ program.command('somecommand'); program.command('anothercommand [options]'); var expectedHelpInformation = [ + 'Usage: [options] [command]', '', - ' Usage: [options] [command]', + 'Options:', '', - ' Options:', + ' -h, --help output usage information', '', - ' -h, --help output usage information', + 'Commands:', '', - ' Commands:', - '', - ' somecommand', - ' anothercommand [options]', - '\n' + ' somecommand', + ' anothercommand [options]', + '' ].join('\n'); program.helpInformation().should.equal(expectedHelpInformation); diff --git a/test/test.command.name.js b/test/test.command.name.js index 4f6a36d0e..0d783e9c9 100644 --- a/test/test.command.name.js +++ b/test/test.command.name.js @@ -18,7 +18,7 @@ program.commands[1].name().should.equal('help'); var output = process.stdout.write.args[0]; output[0].should.containEql([ - ' mycommand [options] this is my command' + ' mycommand [options] this is my command' ].join('\n')); sinon.restore(); diff --git a/test/test.command.nohelp.js b/test/test.command.nohelp.js index 247d6756e..417be64ab 100644 --- a/test/test.command.nohelp.js +++ b/test/test.command.nohelp.js @@ -47,10 +47,10 @@ process.stdout.write.args.length.should.equal(1); var output = process.stdout.write.args[0]; var expect = [ - ' Commands:', + 'Commands:', '', - ' mycommand [options] this is my command', - ' anothercommand [options]', - ' help [cmd] display help for [cmd]' + ' mycommand [options] this is my command', + ' anothercommand [options]', + ' help [cmd] display help for [cmd]' ].join('\n'); output[0].indexOf(expect).should.not.be.equal(-1);