diff --git a/Readme.md b/Readme.md index c2b765350..6391ee7d2 100644 --- a/Readme.md +++ b/Readme.md @@ -35,6 +35,7 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md) - [Display help from code](#display-help-from-code) - [.name](#name) - [.usage](#usage) + - [.description and .summary](#description-and-summary) - [.helpOption(flags, description)](#helpoptionflags-description) - [.addHelpCommand()](#addhelpcommand) - [More configuration](#more-configuration-2) @@ -814,10 +815,11 @@ error: unknown option '--unknown' (add --help for additional information) ``` -You can also show suggestions after an error for an unknown command or option. +The default behaviour is to suggest correct spelling after an error for an unknown command or option. You +can disable this. ```js -program.showSuggestionAfterError(); +program.showSuggestionAfterError(false); ``` ```console @@ -866,6 +868,20 @@ The help will start with: Usage: my-command [global options] command ``` +### .description and .summary + +The description appears in the help for the command. You can optionally supply a shorter +summary to use when listed as a subcommand of the program. + +```js +program + .command("duplicate") + .summary("make a copy") + .description(`Make a copy of the current project. +This may require additional disk space. + `); +``` + ### .helpOption(flags, description) By default every command has a help option. You may change the default help flags and description. Pass false to disable the built-in help option. diff --git a/lib/command.js b/lib/command.js index 4c5089a3f..d1d0c4f95 100644 --- a/lib/command.js +++ b/lib/command.js @@ -48,6 +48,7 @@ class Command extends EventEmitter { this._aliases = []; this._combineFlagAndOptionalValue = true; this._description = ''; + this._summary = ''; this._argsDescription = undefined; // legacy this._enablePositionalOptions = false; this._passThroughOptions = false; @@ -1767,7 +1768,7 @@ Expecting one of '${allowedValues.join("', '")}'`); } /** - * Set the description to `str`. + * Set the description. * * @param {string} [str] * @param {Object} [argsDescription] @@ -1782,6 +1783,18 @@ Expecting one of '${allowedValues.join("', '")}'`); return this; } + /** + * Set the summary. Used when listed as subcommand of parent. + * + * @param {string} [str] + * @return {string|Command} + */ + summary(str) { + if (str === undefined) return this._summary; + this._summary = str; + return this; + } + /** * Set an alias for the command. * diff --git a/lib/help.js b/lib/help.js index 17a2bf83c..9c7fb1ecd 100644 --- a/lib/help.js +++ b/lib/help.js @@ -215,7 +215,8 @@ class Help { } /** - * Get the command description to show in the list of subcommands. + * Get the subcommand summary to show in the list of subcommands. + * (Fallback to description for backwards compatiblity.) * * @param {Command} cmd * @returns {string} @@ -223,7 +224,7 @@ class Help { subcommandDescription(cmd) { // @ts-ignore: overloaded return type - return cmd.description(); + return cmd.summary() || cmd.description(); } /** diff --git a/tests/command.summary.test.js b/tests/command.summary.test.js new file mode 100644 index 000000000..18887c113 --- /dev/null +++ b/tests/command.summary.test.js @@ -0,0 +1,8 @@ +const commander = require('../'); + +test('when set summary then get summary', () => { + const program = new commander.Command(); + const summary = 'abcdef'; + program.summary(summary); + expect(program.summary()).toMatch(summary); +}); diff --git a/tests/help.commandDescription.test.js b/tests/help.commandDescription.test.js deleted file mode 100644 index 49eb797cd..000000000 --- a/tests/help.commandDescription.test.js +++ /dev/null @@ -1,20 +0,0 @@ -const commander = require('../'); - -// These are tests of the Help class, not of the Command help. -// There is some overlap with the higher level Command tests (which predate Help). - -describe('subcommandDescription', () => { - test('when program has no description then empty string', () => { - const program = new commander.Command(); - const helper = new commander.Help(); - expect(helper.subcommandDescription(program)).toEqual(''); - }); - - test('when program has description then return description', () => { - const description = 'description'; - const program = new commander.Command(); - program.description(description); - const helper = new commander.Help(); - expect(helper.subcommandDescription(program)).toEqual(description); - }); -}); diff --git a/tests/help.subcommandDescription.test.js b/tests/help.subcommandDescription.test.js new file mode 100644 index 000000000..677454266 --- /dev/null +++ b/tests/help.subcommandDescription.test.js @@ -0,0 +1,37 @@ +const commander = require('../'); + +// These are tests of the Help class, not of the Command help. +// There is some overlap with the higher level Command tests (which predate Help). + +describe('subcommandDescription', () => { + test('when program has no summary or description then empty string', () => { + const program = new commander.Command(); + const helper = new commander.Help(); + expect(helper.subcommandDescription(program)).toEqual(''); + }); + + test('when program has summary then return summary', () => { + const summary = 'summary'; + const program = new commander.Command(); + program.summary(summary); + const helper = new commander.Help(); + expect(helper.subcommandDescription(program)).toEqual(summary); + }); + + test('when program has description then return description', () => { + const description = 'description'; + const program = new commander.Command(); + program.description(description); + const helper = new commander.Help(); + expect(helper.subcommandDescription(program)).toEqual(description); + }); + + test('when program has summary and description then return summary', () => { + const summary = 'summary'; + const program = new commander.Command(); + program.summary(summary); + program.description('description'); + const helper = new commander.Help(); + expect(helper.subcommandDescription(program)).toEqual(summary); + }); +}); diff --git a/typings/index.d.ts b/typings/index.d.ts index e1b80e3d2..6aa791bf1 100644 --- a/typings/index.d.ts +++ b/typings/index.d.ts @@ -202,7 +202,7 @@ export class Help { /** Get the command term to show in the list of subcommands. */ subcommandTerm(cmd: Command): string; - /** Get the command description to show in the list of subcommands. */ + /** Get the command summary to show in the list of subcommands. */ subcommandDescription(cmd: Command): string; /** Get the option term to show in the list of options. */ optionTerm(option: Option): string; @@ -718,6 +718,18 @@ export class Command { */ description(): string; + /** + * Set the summary. Used when listed as subcommand of parent. + * + * @returns `this` command for chaining + */ + + summary(str: string): this; + /** + * Get the summary. + */ + summary(): string; + /** * Set an alias for the command. * diff --git a/typings/index.test-d.ts b/typings/index.test-d.ts index 5e8b8397d..a908a1a16 100644 --- a/typings/index.test-d.ts +++ b/typings/index.test-d.ts @@ -239,6 +239,10 @@ expectType(program.description('my description')); expectType(program.description()); expectType(program.description('my description of command with arg foo', { foo: 'foo description' })); // deprecated +// summary +expectType(program.summary('my summary')); +expectType(program.summary()); + // alias expectType(program.alias('my alias')); expectType(program.alias());