From 8b6da04692a67b95e05a73c5d39b147eff4f5676 Mon Sep 17 00:00:00 2001 From: John Gee Date: Sun, 25 Jun 2023 21:38:06 +1200 Subject: [PATCH 1/2] Add example of displaying custom usage in subcommand list --- examples/help-subcommands.js | 48 ++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 examples/help-subcommands.js diff --git a/examples/help-subcommands.js b/examples/help-subcommands.js new file mode 100644 index 000000000..935f12ac3 --- /dev/null +++ b/examples/help-subcommands.js @@ -0,0 +1,48 @@ +// const commander = require('commander'); // (normal include) +const commander = require('../'); // include commander in git clone of commander repo + +// This is a contrived example to show some different ways to display the list of subcommands. +// By default the subcommand list includes a simple usage. If you have defined a custom usage, +// you may prefer to show these. Or you may prefer to keep the list simple and leave the +// usage details for the subcommand help. +// +// Normally you would customise the help on the program before adding the subcommands and +// it will apply to all the subcommands too. For this example, we use `.configureHelp()` on +// the subcommand so we can see different styles. + +function addSubcommands(cmd) { + cmd.command('make ') + .usage('-root ROOTDIR [-abc] ') + .requiredOption('--root ') + .option('-a') + .option('-b') + .option('-c') + .summary('example command with custom usage') + .description('this is displayed in the full help and not in the list of subcommands of the parent'); + cmd.command('serve') + .option('--port ') + .description('example command with just a description'); +} + +const program = new commander.Command(); + +const plain = program.command('plain') + .description('has default help'); +addSubcommands(plain); + +const custom = program.command('custom') + .description('has custom help which shows custom usage') + .configureHelp({ subcommandTerm: (cmd) => cmd.name() + ' ' + cmd.usage() }); +addSubcommands(custom); + +const nameOnly = program.command('name') + .description('has custom help which shows just the subcommand name and no usage') + .configureHelp({ subcommandTerm: (cmd) => cmd.name() }); +addSubcommands(nameOnly); + +program.parse(); + +// Try the following: +// node help-subcommands help plain +// node help-subcommands help custom +// node help-subcommands help name From 00736f06c62c94237bc177d43a97e5cdb533caca Mon Sep 17 00:00:00 2001 From: John Gee Date: Sun, 25 Jun 2023 21:58:24 +1200 Subject: [PATCH 2/2] Make example more focused --- examples/help-subcommands-usage.js | 29 ++++++++++++++++++ examples/help-subcommands.js | 48 ------------------------------ 2 files changed, 29 insertions(+), 48 deletions(-) create mode 100644 examples/help-subcommands-usage.js delete mode 100644 examples/help-subcommands.js diff --git a/examples/help-subcommands-usage.js b/examples/help-subcommands-usage.js new file mode 100644 index 000000000..a2f71476f --- /dev/null +++ b/examples/help-subcommands-usage.js @@ -0,0 +1,29 @@ +// const commander = require('commander'); // (normal include) +const commander = require('../'); // include commander in git clone of commander repo + +// By default the subcommand list includes a fairly simple usage. If you have added a custom usage +// to the subcommands you may wish to configure the help to show these instead. +// +// See also ./configure-help.js which shows configuring the subcommand list to have no usage at all +// and just the subcommand name. + +const program = new commander.Command() + .configureHelp({ subcommandTerm: (cmd) => cmd.name() + ' ' + cmd.usage() }); + +program.command('make ') + .usage('-root ROOTDIR [-abc] ') + .requiredOption('--root ') + .option('-a') + .option('-b') + .option('-c') + .summary('example command with custom usage') + .description('this full description is displayed in the full help and not in the list of subcommands'); + +program.command('serve ') + .option('--port ') + .description('example command with default simple usage'); + +program.parse(); + +// Try the following: +// node help-subcommands-usage help diff --git a/examples/help-subcommands.js b/examples/help-subcommands.js deleted file mode 100644 index 935f12ac3..000000000 --- a/examples/help-subcommands.js +++ /dev/null @@ -1,48 +0,0 @@ -// const commander = require('commander'); // (normal include) -const commander = require('../'); // include commander in git clone of commander repo - -// This is a contrived example to show some different ways to display the list of subcommands. -// By default the subcommand list includes a simple usage. If you have defined a custom usage, -// you may prefer to show these. Or you may prefer to keep the list simple and leave the -// usage details for the subcommand help. -// -// Normally you would customise the help on the program before adding the subcommands and -// it will apply to all the subcommands too. For this example, we use `.configureHelp()` on -// the subcommand so we can see different styles. - -function addSubcommands(cmd) { - cmd.command('make ') - .usage('-root ROOTDIR [-abc] ') - .requiredOption('--root ') - .option('-a') - .option('-b') - .option('-c') - .summary('example command with custom usage') - .description('this is displayed in the full help and not in the list of subcommands of the parent'); - cmd.command('serve') - .option('--port ') - .description('example command with just a description'); -} - -const program = new commander.Command(); - -const plain = program.command('plain') - .description('has default help'); -addSubcommands(plain); - -const custom = program.command('custom') - .description('has custom help which shows custom usage') - .configureHelp({ subcommandTerm: (cmd) => cmd.name() + ' ' + cmd.usage() }); -addSubcommands(custom); - -const nameOnly = program.command('name') - .description('has custom help which shows just the subcommand name and no usage') - .configureHelp({ subcommandTerm: (cmd) => cmd.name() }); -addSubcommands(nameOnly); - -program.parse(); - -// Try the following: -// node help-subcommands help plain -// node help-subcommands help custom -// node help-subcommands help name