commander - npm Package Compare versions

Comparing version 8.0.0 to 8.1.0

lib/argument.js

@@ -112,2 +112,18 @@ const { InvalidArgumentError } = require('./error.js');
   };
+
+  /**
+   * Make option-argument required.
+   */
+  argRequired() {
+    this.required = true;
+    return this;
+  }
+
+  /**
+   * Make option-argument optional.
+   */
+  argOptional() {
+    this.required = false;
+    return this;
+  }
 }
@@ -114,0 +130,0 @@

lib/command.js

@@ -77,2 +77,31 @@ const EventEmitter = require('events').EventEmitter;
   /**
+   * Copy settings that are useful to have in common across root command and subcommands.
+   *
+   * (Used internally when adding a command using `.command()` so subcommands inherit parent settings.)
+   *
+   * @param {Command} sourceCommand
+   * @return {Command} returns `this` for executable command
+   */
+  copyInheritedSettings(sourceCommand) {
+    this._outputConfiguration = sourceCommand._outputConfiguration;
+    this._hasHelpOption = sourceCommand._hasHelpOption;
+    this._helpFlags = sourceCommand._helpFlags;
+    this._helpDescription = sourceCommand._helpDescription;
+    this._helpShortFlag = sourceCommand._helpShortFlag;
+    this._helpLongFlag = sourceCommand._helpLongFlag;
+    this._helpCommandName = sourceCommand._helpCommandName;
+    this._helpCommandnameAndArgs = sourceCommand._helpCommandnameAndArgs;
+    this._helpCommandDescription = sourceCommand._helpCommandDescription;
+    this._helpConfiguration = sourceCommand._helpConfiguration;
+    this._exitCallback = sourceCommand._exitCallback;
+    this._storeOptionsAsProperties = sourceCommand._storeOptionsAsProperties;
+    this._combineFlagAndOptionalValue = sourceCommand._combineFlagAndOptionalValue;
+    this._allowExcessArguments = sourceCommand._allowExcessArguments;
+    this._enablePositionalOptions = sourceCommand._enablePositionalOptions;
+    this._showHelpAfterError = sourceCommand._showHelpAfterError;
+
+    return this;
+  }
+
+  /**
    * Define a command.
@@ -82,17 +111,16 @@ *
    *
-   * Examples:
+   * @example
+   * // Command implemented using action handler (description is supplied separately to `.command`)
+   * program
+   *   .command('clone <source> [destination]')
+   *   .description('clone a repository into a newly created directory')
+   *   .action((source, destination) => {
+   *     console.log('clone command called');
+   *   });
    *
-   *      // Command implemented using action handler (description is supplied separately to `.command`)
-   *      program
-   *        .command('clone <source> [destination]')
-   *        .description('clone a repository into a newly created directory')
-   *        .action((source, destination) => {
-   *          console.log('clone command called');
-   *        });
+   * // Command implemented using separate executable file (description is second parameter to `.command`)
+   * program
+   *   .command('start <service>', 'start named service')
+   *   .command('stop [service]', 'stop named service, or all if no name supplied');
    *
-   *      // Command implemented using separate executable file (description is second parameter to `.command`)
-   *      program
-   *        .command('start <service>', 'start named service')
-   *        .command('stop [service]', 'stop named service, or all if no name supplied');
-   *
    * @param {string} nameAndArgs - command name and arguments, args are `<required>` or `[optional]` and last may also be `variadic...`
@@ -113,4 +141,4 @@ * @param {Object|string} [actionOptsOrExecDesc] - configuration options (for action), or description (for executable)
     const [, name, args] = nameAndArgs.match(/([^ ]+) *(.*)/);
+
     const cmd = this.createCommand(name);
-
     if (desc) {
@@ -121,22 +149,3 @@ cmd.description(desc);
     if (opts.isDefault) this._defaultCommandName = cmd._name;
-
-    cmd._outputConfiguration = this._outputConfiguration;
-
     cmd._hidden = !!(opts.noHelp || opts.hidden); // noHelp is deprecated old name for hidden
-    cmd._hasHelpOption = this._hasHelpOption;
-    cmd._helpFlags = this._helpFlags;
-    cmd._helpDescription = this._helpDescription;
-    cmd._helpShortFlag = this._helpShortFlag;
-    cmd._helpLongFlag = this._helpLongFlag;
-    cmd._helpCommandName = this._helpCommandName;
-    cmd._helpCommandnameAndArgs = this._helpCommandnameAndArgs;
-    cmd._helpCommandDescription = this._helpCommandDescription;
-    cmd._helpConfiguration = this._helpConfiguration;
-    cmd._exitCallback = this._exitCallback;
-    cmd._storeOptionsAsProperties = this._storeOptionsAsProperties;
-    cmd._combineFlagAndOptionalValue = this._combineFlagAndOptionalValue;
-    cmd._allowExcessArguments = this._allowExcessArguments;
-    cmd._enablePositionalOptions = this._enablePositionalOptions;
-    cmd._showHelpAfterError = this._showHelpAfterError;
-
     cmd._executableFile = opts.executableFile || null; // Custom name for executable file, set missing to null to match constructor
@@ -146,2 +155,3 @@ if (args) cmd.arguments(args);
     cmd.parent = this;
+    cmd.copyInheritedSettings(this);
 
@@ -198,10 +208,10 @@ if (desc) return this;
    *
-   *    // functions to change where being written, stdout and stderr
-   *    writeOut(str)
-   *    writeErr(str)
-   *    // matching functions to specify width for wrapping help
-   *    getOutHelpWidth()
-   *    getErrHelpWidth()
-   *    // functions based on what is being written out
-   *    outputError(str, write) // used for displaying errors, and not used for displaying help
+   *     // functions to change where being written, stdout and stderr
+   *     writeOut(str)
+   *     writeErr(str)
+   *     // matching functions to specify width for wrapping help
+   *     getOutHelpWidth()
+   *     getErrHelpWidth()
+   *     // functions based on what is being written out
+   *     outputError(str, write) // used for displaying errors, and not used for displaying help
    *
@@ -287,6 +297,5 @@ * @param {Object} [configuration] - configuration options
    * @example
+   * program.argument('<input-file>');
+   * program.argument('[output-file]');
    *
-   *     program.argument('<input-file>');
-   *     program.argument('[output-file]');
-   *
    * @param {string} name
@@ -315,5 +324,4 @@ * @param {string} [description]
    * @example
+   * program.arguments('<cmd> [env]');
    *
-   *     program.arguments('<cmd> [env]');
-   *
    * @param {string} names
@@ -449,11 +457,10 @@ * @return {Command} `this` command for chaining
    *
-   * Examples:
+   * @example
+   * program
+   *   .command('help')
+   *   .description('display verbose help')
+   *   .action(function() {
+   *      // output help here
+   *   });
    *
-   *      program
-   *        .command('help')
-   *        .description('display verbose help')
-   *        .action(function() {
-   *           // output help here
-   *        });
-   *
    * @param {Function} fn
@@ -596,38 +603,37 @@ * @return {Command} `this` command for chaining
    *
-   *    "-p, --pepper"
-   *    "-p|--pepper"
-   *    "-p --pepper"
+   *     "-p, --pepper"
+   *     "-p|--pepper"
+   *     "-p --pepper"
    *
-   * Examples:
+   * @example
+   * // simple boolean defaulting to undefined
+   * program.option('-p, --pepper', 'add pepper');
    *
-   *     // simple boolean defaulting to undefined
-   *     program.option('-p, --pepper', 'add pepper');
+   * program.pepper
+   * // => undefined
    *
-   *     program.pepper
-   *     // => undefined
+   * --pepper
+   * program.pepper
+   * // => true
    *
-   *     --pepper
-   *     program.pepper
-   *     // => true
+   * // simple boolean defaulting to true (unless non-negated option is also defined)
+   * program.option('-C, --no-cheese', 'remove cheese');
    *
-   *     // simple boolean defaulting to true (unless non-negated option is also defined)
-   *     program.option('-C, --no-cheese', 'remove cheese');
+   * program.cheese
+   * // => true
    *
-   *     program.cheese
-   *     // => true
+   * --no-cheese
+   * program.cheese
+   * // => false
    *
-   *     --no-cheese
-   *     program.cheese
-   *     // => false
+   * // required argument
+   * program.option('-C, --chdir <path>', 'change the working directory');
    *
-   *     // required argument
-   *     program.option('-C, --chdir <path>', 'change the working directory');
+   * --chdir /tmp
+   * program.chdir
+   * // => "/tmp"
    *
-   *     --chdir /tmp
-   *     program.chdir
-   *     // => "/tmp"
+   * // optional argument
+   * program.option('-c, --cheese [type]', 'add cheese [marble]');
    *
-   *     // optional argument
-   *     program.option('-c, --cheese [type]', 'add cheese [marble]');
-   *
    * @param {string} flags
@@ -664,8 +670,7 @@ * @param {string} [description]
    *
-   * Examples:
+   * @example
+   * // for `.option('-f,--flag [value]'):
+   * program.combineFlagAndOptionalValue(true);  // `-f80` is treated like `--flag=80`, this is the default behaviour
+   * program.combineFlagAndOptionalValue(false) // `-fb` is treated like `-f -b`
    *
-   *    // for `.option('-f,--flag [value]'):
-   *    .combineFlagAndOptionalValue(true)  // `-f80` is treated like `--flag=80`, this is the default behaviour
-   *    .combineFlagAndOptionalValue(false) // `-fb` is treated like `-f -b`
-   *
    * @param {Boolean} [combine=true] - if `true` or omitted, an optional value can be specified directly after the flag.
@@ -838,8 +843,7 @@ */
    *
-   * Examples:
+   * @example
+   * program.parse(process.argv);
+   * program.parse(); // implicitly use process.argv and auto-detect node vs electron conventions
+   * program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
    *
-   *      program.parse(process.argv);
-   *      program.parse(); // implicitly use process.argv and auto-detect node vs electron conventions
-   *      program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
-   *
    * @param {string[]} [argv] - optional, defaults to process.argv
@@ -866,8 +870,7 @@ * @param {Object} [parseOptions] - optionally specify style of options with from: node/user/electron
    *
-   * Examples:
+   * @example
+   * await program.parseAsync(process.argv);
+   * await program.parseAsync(); // implicitly use process.argv and auto-detect node vs electron conventions
+   * await program.parseAsync(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
    *
-   *      await program.parseAsync(process.argv);
-   *      await program.parseAsync(); // implicitly use process.argv and auto-detect node vs electron conventions
-   *      await program.parseAsync(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
-   *
    * @param {string[]} [argv]
@@ -1261,7 +1264,7 @@ * @param {Object} [parseOptions]
    *
-   *    argv => operands, unknown
-   *    --known kkk op => [op], []
-   *    op --known kkk => [op], []
-   *    sub --unknown uuu op => [sub], [--unknown uuu op]
-   *    sub -- --unknown uuu op => [sub --unknown uuu op], []
+   *     argv => operands, unknown
+   *     --known kkk op => [op], []
+   *     op --known kkk => [op], []
+   *     sub --unknown uuu op => [sub], [--unknown uuu op]
+   *     sub -- --unknown uuu op => [sub --unknown uuu op], []
    *
@@ -1676,10 +1679,3 @@ * @param {String[]} argv
 
-    const groupListeners = [];
-    let command = this;
-    while (command) {
-      groupListeners.push(command); // ordered from current command to root
-      command = command.parent;
-    }
-
-    groupListeners.slice().reverse().forEach(command => command.emit('beforeAllHelp', context));
+    getCommandAndParents(this).reverse().forEach(command => command.emit('beforeAllHelp', context));
     this.emit('beforeHelp', context);
@@ -1698,3 +1694,3 @@
     this.emit('afterHelp', context);
-    groupListeners.forEach(command => command.emit('afterAllHelp', context));
+    getCommandAndParents(this).forEach(command => command.emit('afterAllHelp', context));
   };
@@ -1701,0 +1697,0 @@

package.json

 {
   "name": "commander",
-  "version": "8.0.0",
+  "version": "8.1.0",
   "description": "the complete solution for node.js command-line programs",
@@ -5,0 +5,0 @@ "keywords": [

Readme.md

@@ -116,3 +116,3 @@ # Commander.js
 The two most used option types are a boolean option, and an option which takes its value
-from the following argument (declared with angle brackets like `--expect <value>`). Both are `undefined` unless specified on command line.  
+from the following argument (declared with angle brackets like `--expect <value>`). Both are `undefined` unless specified on command line.
 
@@ -430,3 +430,3 @@ Example file: [options-common.js](./examples/options-common.js)
 
-Configuration options can be passed with the call to `.command()` and `.addCommand()`. Specifying `hidden: true` will 
+Configuration options can be passed with the call to `.command()` and `.addCommand()`. Specifying `hidden: true` will
 remove the command from the generated help output. Specifying `isDefault: true` will run the subcommand if no other
@@ -441,3 +441,3 @@ subcommand is specified ([example](./examples/defaultCommand.js)).
 
-To configure a command, you can use `.argument()` to specify each expected command-argument. 
+To configure a command, you can use `.argument()` to specify each expected command-argument.
 You supply the argument name and an optional description. The argument may be `<required>` or `[optional]`.
@@ -519,3 +519,3 @@ You can specify a default value for an optional command-argument.
 The action handler gets passed a parameter for each command-argument you declared, and two additional parameters
-which are the parsed options and the command object itself. 
+which are the parsed options and the command object itself.
 
@@ -637,3 +637,3 @@ Example file: [thank.js](./examples/thank.js)
 
-You can add extra text to be displayed along with the built-in help. 
+You can add extra text to be displayed along with the built-in help.
 
@@ -672,3 +672,3 @@ Example file: [custom-help](./examples/custom-help)
 
-The positions "beforeAll" and "afterAll" apply to the command and all its subcommands. 
+The positions "beforeAll" and "afterAll" apply to the command and all its subcommands.
 
@@ -682,3 +682,3 @@ The second parameter can be a string, or a function returning a string. The function is passed a context object for your convenience. The properties are:
 
-The default behaviour for usage errors is to just display a short error message. 
+The default behaviour for usage errors is to just display a short error message.
 You can change the behaviour to show the full help or a custom help message after an error.
@@ -757,3 +757,3 @@
 
-```
+```js
 program.configureHelp({
@@ -820,3 +820,3 @@ sortSubcommands: true,
 before the command-arguments, use `.passThroughOptions()`. This lets you pass the  arguments and following options through to another program
-without needing to use `--` to end the option processing. 
+without needing to use `--` to end the option processing.
 To use pass through options in a subcommand, the program needs to enable positional options.
@@ -838,3 +838,3 @@
 
-### Legacy options as properties 
+### Legacy options as properties
 
@@ -999,3 +999,3 @@ Before Commander 7, the option values were stored as properties on the command.
   );
-  
+
 program.parse(process.argv);
@@ -1002,0 +1002,0 @@ ```

typings/index.d.ts

@@ -16,5 +16,5 @@ // Type definitions for commander
    * Constructs the CommanderError class
-   * @param {number} exitCode suggested exit code which could be used with process.exit
-   * @param {string} code an id string representing the error
-   * @param {string} message human-readable description of the error
+   * @param exitCode - suggested exit code which could be used with process.exit
+   * @param code - an id string representing the error
+   * @param message - human-readable description of the error
    * @constructor
@@ -28,3 +28,3 @@ */
    * Constructs the InvalidArgumentError class
-   * @param {string} [message] explanation of why argument is invalid
+   * @param message - explanation of why argument is invalid
    * @constructor
@@ -45,5 +45,2 @@ */
    * indicate this with <> around the name. Put [] around the name for an optional argument.
-   *
-   * @param {string} name
-   * @param {string} [description]
    */
@@ -72,2 +69,11 @@ constructor(arg: string, description?: string);
 
+  /**
+   * Make option-argument required.
+   */
+   argRequired(): this;
+
+  /**
+   * Make option-argument optional.
+   */
+  argOptional(): this;
   }
@@ -248,8 +254,8 @@
    * ```ts
-   *  program
-   *    .command('clone <source> [destination]')
-   *    .description('clone a repository into a newly created directory')
-   *    .action((source, destination) => {
-   *      console.log('clone command called');
-   *    });
+   * program
+   *   .command('clone <source> [destination]')
+   *   .description('clone a repository into a newly created directory')
+   *   .action((source, destination) => {
+   *     console.log('clone command called');
+   *   });
    * ```
@@ -314,6 +320,7 @@ *
    * @example
+   * ```
+   * program.argument('<input-file>');
+   * program.argument('[output-file]');
+   * ```
    *
-   *     program.argument('<input-file>');
-   *     program.argument('[output-file]');
-   *
    * @returns `this` command for chaining
@@ -337,5 +344,6 @@ */
    * @example
+   * ```
+   * program.arguments('<cmd> [env]');
+   * ```
    *
-   *     program.arguments('<cmd> [env]');
-   *
    * @returns `this` command for chaining
@@ -348,5 +356,8 @@ */
    *
-   *    addHelpCommand() // force on
-   *    addHelpCommand(false); // force off
-   *    addHelpCommand('help [cmd]', 'display help for [cmd]'); // force on with custom details
+   * @example
+   * ```
+   * addHelpCommand() // force on
+   * addHelpCommand(false); // force off
+   * addHelpCommand('help [cmd]', 'display help for [cmd]'); // force on with custom details
+   * ```
    *
@@ -386,11 +397,12 @@ * @returns `this` command for chaining
    * The configuration properties are all functions:
-   *
-   *    // functions to change where being written, stdout and stderr
-   *    writeOut(str)
-   *    writeErr(str)
-   *    // matching functions to specify width for wrapping help
-   *    getOutHelpWidth()
-   *    getErrHelpWidth()
-   *    // functions based on what is being written out
-   *    outputError(str, write) // used for displaying errors, and not used for displaying help
+   * ```
+   * // functions to change where being written, stdout and stderr
+   * writeOut(str)
+   * writeErr(str)
+   * // matching functions to specify width for wrapping help
+   * getOutHelpWidth()
+   * getErrHelpWidth()
+   * // functions based on what is being written out
+   * outputError(str, write) // used for displaying errors, and not used for displaying help
+   * ```
    */
@@ -402,2 +414,9 @@ configureOutput(configuration: OutputConfiguration): this;
   /**
+   * Copy settings that are useful to have in common across root command and subcommands.
+   *
+   * (Used internally when adding a command using `.command()` so subcommands inherit parent settings.)
+   */
+   copyInheritedSettings(sourceCommand: Command): this;
+
+  /**
    * Display the help or a custom message after an error occurs.
@@ -411,8 +430,10 @@ */
    * @example
-   *      program
-   *        .command('help')
-   *        .description('display verbose help')
-   *        .action(function() {
-   *           // output help here
-   *        });
+   * ```
+   * program
+   *   .command('help')
+   *   .description('display verbose help')
+   *   .action(function() {
+   *     // output help here
+   *   });
+   * ```
    *
@@ -431,33 +452,35 @@ * @returns `this` command for chaining
    *
-   *    "-p, --pepper"
-   *    "-p|--pepper"
-   *    "-p --pepper"
+   *     "-p, --pepper"
+   *     "-p|--pepper"
+   *     "-p --pepper"
    *
    * @example
-   *     // simple boolean defaulting to false
-   *     program.option('-p, --pepper', 'add pepper');
+   * ```
+   * // simple boolean defaulting to false
+   *  program.option('-p, --pepper', 'add pepper');
    *
-   *     --pepper
-   *     program.pepper
-   *     // => Boolean
+   *  --pepper
+   *  program.pepper
+   *  // => Boolean
    *
-   *     // simple boolean defaulting to true
-   *     program.option('-C, --no-cheese', 'remove cheese');
+   *  // simple boolean defaulting to true
+   *  program.option('-C, --no-cheese', 'remove cheese');
    *
-   *     program.cheese
-   *     // => true
+   *  program.cheese
+   *  // => true
    *
-   *     --no-cheese
-   *     program.cheese
-   *     // => false
+   *  --no-cheese
+   *  program.cheese
+   *  // => false
    *
-   *     // required argument
-   *     program.option('-C, --chdir <path>', 'change the working directory');
+   *  // required argument
+   *  program.option('-C, --chdir <path>', 'change the working directory');
    *
-   *     --chdir /tmp
-   *     program.chdir
-   *     // => "/tmp"
+   *  --chdir /tmp
+   *  program.chdir
+   *  // => "/tmp"
    *
-   *     // optional argument
-   *     program.option('-c, --cheese [type]', 'add cheese [marble]');
+   *  // optional argument
+   *  program.option('-c, --cheese [type]', 'add cheese [marble]');
+   * ```
    *
@@ -522,5 +545,7 @@ * @returns `this` command for chaining
    * @example
-   *    // for `.option('-f,--flag [value]'):
-   *   .combineFlagAndOptionalValue(true)  // `-f80` is treated like `--flag=80`, this is the default behaviour
-   *   .combineFlagAndOptionalValue(false) // `-fb` is treated like `-f -b`
+   * ```
+   * // for `.option('-f,--flag [value]'):
+   * .combineFlagAndOptionalValue(true)  // `-f80` is treated like `--flag=80`, this is the default behaviour
+   * .combineFlagAndOptionalValue(false) // `-fb` is treated like `-f -b`
+   * ```
    *
@@ -572,8 +597,9 @@ * @returns `this` command for chaining
    *
-   * Examples:
+   * @example
+   * ```
+   * program.parse(process.argv);
+   * program.parse(); // implicitly use process.argv and auto-detect node vs electron conventions
+   * program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
+   * ```
    *
-   *      program.parse(process.argv);
-   *      program.parse(); // implicitly use process.argv and auto-detect node vs electron conventions
-   *      program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
-   *
    * @returns `this` command for chaining
@@ -591,8 +617,9 @@ */
    *
-   * Examples:
+   * @example
+   * ```
+   * program.parseAsync(process.argv);
+   * program.parseAsync(); // implicitly use process.argv and auto-detect node vs electron conventions
+   * program.parseAsync(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
+   * ```
    *
-   *      program.parseAsync(process.argv);
-   *      program.parseAsync(); // implicitly use process.argv and auto-detect node vs electron conventions
-   *      program.parseAsync(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
-   *
    * @returns Promise
@@ -606,8 +633,7 @@ */
    *
-   * @example
-   *    argv => operands, unknown
-   *    --known kkk op => [op], []
-   *    op --known kkk => [op], []
-   *    sub --unknown uuu op => [sub], [--unknown uuu op]
-   *    sub -- --unknown uuu op => [sub --unknown uuu op], []
+   *     argv => operands, unknown
+   *     --known kkk op => [op], []
+   *     op --known kkk => [op], []
+   *     sub --unknown uuu op => [sub], [--unknown uuu op]
+   *     sub -- --unknown uuu op => [sub --unknown uuu op], []
    */
@@ -614,0 +640,0 @@ parseOptions(argv: string[]): ParseOptionsResult;

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

143321

increased by0.46%

Lines of code

3040

increased by1.2%

No dependency changes