From 7770e01096f06492e9f6f1706590e6764cc06170 Mon Sep 17 00:00:00 2001 From: John Gee Date: Thu, 10 Sep 2020 21:35:02 +1200 Subject: [PATCH 1/4] Add test for command-arguments description in help --- tests/command.help.test.js | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/tests/command.help.test.js b/tests/command.help.test.js index c2ed34b3c..2e0617452 100644 --- a/tests/command.help.test.js +++ b/tests/command.help.test.js @@ -139,3 +139,23 @@ test('when no options then Options not includes in helpInformation', () => { const helpInformation = program.helpInformation(); expect(helpInformation).not.toMatch('Options'); }); + +test('when arguments then included in helpInformation', () => { + const program = new commander.Command(); + program + .name('foo') + .arguments(''); + const helpInformation = program.helpInformation(); + expect(helpInformation).toMatch('Usage: foo [options] '); +}); + +test('when arguments described then included in helpInformation', () => { + const program = new commander.Command(); + program + .arguments('') + .helpOption(false) + .description('description', { file: 'input source' }); + const helpInformation = program.helpInformation(); + expect(helpInformation).toMatch('Arguments:'); + expect(helpInformation).toMatch(/file +input source/); +}); From ebb6bc61b98c909012af60f2c4db610a6bb255a7 Mon Sep 17 00:00:00 2001 From: John Gee Date: Thu, 10 Sep 2020 21:52:01 +1200 Subject: [PATCH 2/4] Remove blank line after Arguments: to match Options and Commands --- index.js | 1 - 1 file changed, 1 deletion(-) diff --git a/index.js b/index.js index c1b67b7b2..c3ad03fe5 100644 --- a/index.js +++ b/index.js @@ -1576,7 +1576,6 @@ Read more on https://git.io/JJc0W`); const columns = process.stdout.columns || 80; const descriptionWidth = columns - width - 5; desc.push('Arguments:'); - desc.push(''); this._args.forEach((arg) => { desc.push(' ' + pad(arg.name, width) + ' ' + wrap(argsDescription[arg.name] || '', descriptionWidth, width + 4)); }); From 6ebbf8d07faa6ec3f99cd3d4e67b60ed77d53ad1 Mon Sep 17 00:00:00 2001 From: John Gee Date: Thu, 10 Sep 2020 21:54:01 +1200 Subject: [PATCH 3/4] Add argument decription to README and example --- Readme.md | 5 +++++ examples/env | 9 +++++++++ tests/command.help.test.js | 3 +-- 3 files changed, 15 insertions(+), 2 deletions(-) diff --git a/Readme.md b/Readme.md index 1c696aca5..88f4f4c43 100644 --- a/Readme.md +++ b/Readme.md @@ -368,6 +368,7 @@ Configuration options can be passed with the call to `.command()` and `.addComma ### Specify the argument syntax You use `.arguments` to specify the arguments for the top-level command, and for subcommands they are usually included in the `.command` call. Angled brackets (e.g. ``) indicate required input. Square brackets (e.g. `[optional]`) indicate optional input. +You can optionally describe the arguments in the help by supplying a hash as second parameter to `.description()`. Example file: [env](./examples/env) @@ -375,6 +376,10 @@ Example file: [env](./examples/env) program .version('0.1.0') .arguments(' [env]') + .description('test command', { + cmd: 'command to run', + env: 'environment to run test in' + }) .action(function (cmd, env) { console.log('command:', cmd); console.log('environment:', env || 'no environment given'); diff --git a/examples/env b/examples/env index ba91bfdc4..836a72c13 100755 --- a/examples/env +++ b/examples/env @@ -12,9 +12,18 @@ let envValue; program .version('0.0.1') .arguments(' [env]') + .description('test command', { + cmd: 'command to run', + env: 'environment to run test in' + }) .action(function(cmdValue, envValue) { console.log('command:', cmdValue); console.log('environment:', envValue || 'no environment given'); }); program.parse(process.argv); + +// Try the following: +// node env --help +// node env add +// node env add browser diff --git a/tests/command.help.test.js b/tests/command.help.test.js index 2e0617452..88e290972 100644 --- a/tests/command.help.test.js +++ b/tests/command.help.test.js @@ -156,6 +156,5 @@ test('when arguments described then included in helpInformation', () => { .helpOption(false) .description('description', { file: 'input source' }); const helpInformation = program.helpInformation(); - expect(helpInformation).toMatch('Arguments:'); - expect(helpInformation).toMatch(/file +input source/); + expect(helpInformation).toMatch(/Arguments:\n +file +input source/); }); From 723a324e3a9a320d5409e502c6775ea548cb4b0d Mon Sep 17 00:00:00 2001 From: John Gee Date: Thu, 10 Sep 2020 22:03:52 +1200 Subject: [PATCH 4/4] Put back extra line so no chnage in code --- index.js | 1 + tests/command.help.test.js | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/index.js b/index.js index c3ad03fe5..c1b67b7b2 100644 --- a/index.js +++ b/index.js @@ -1576,6 +1576,7 @@ Read more on https://git.io/JJc0W`); const columns = process.stdout.columns || 80; const descriptionWidth = columns - width - 5; desc.push('Arguments:'); + desc.push(''); this._args.forEach((arg) => { desc.push(' ' + pad(arg.name, width) + ' ' + wrap(argsDescription[arg.name] || '', descriptionWidth, width + 4)); }); diff --git a/tests/command.help.test.js b/tests/command.help.test.js index 88e290972..32c58b329 100644 --- a/tests/command.help.test.js +++ b/tests/command.help.test.js @@ -156,5 +156,5 @@ test('when arguments described then included in helpInformation', () => { .helpOption(false) .description('description', { file: 'input source' }); const helpInformation = program.helpInformation(); - expect(helpInformation).toMatch(/Arguments:\n +file +input source/); + expect(helpInformation).toMatch(/Arguments:\n\n +file +input source/); // [sic], extra line });