commander - npm Package Compare versions

Comparing version 4.0.0-0 to 4.0.0-1

CHANGELOG.md

@@ -10,2 +10,8 @@ # Changelog
 
+## [4.0.0-1] Prerelease (2019-10-08)
+
+### Added
+
+* support for declaring required options with `.requiredOptions()` ([#1071])
+
 ## [4.0.0-0] Prerelease (2019-10-01)
@@ -494,4 +500,6 @@
 [#1053]: https://github.com/tj/commander.js/pull/1053
+[#1071]: https://github.com/tj/commander.js/pull/1071
 
 [Unreleased]: https://github.com/tj/commander.js/compare/master...develop
+[4.0.0-1]: https://github.com/tj/commander.js/compare/v4.0.0-0..v4.0.0-1
 [4.0.0-0]: https://github.com/tj/commander.js/compare/v3.0.2...v4.0.0-0
@@ -498,0 +506,0 @@ [3.0.2]: https://github.com/tj/commander.js/compare/v3.0.1...v3.0.2

index.js

@@ -46,4 +46,5 @@ /**
   this.flags = flags;
-  this.required = flags.indexOf('<') >= 0;
-  this.optional = flags.indexOf('[') >= 0;
+  this.required = flags.indexOf('<') >= 0; // A value must be supplied when the option is specified.
+  this.optional = flags.indexOf('[') >= 0; // A value is optional when the option is specified.
+  this.mandatory = false; // The option must have a value after parsing, which usually means it must be specified on command line.
   this.negate = flags.indexOf('-no-') !== -1;
@@ -369,54 +370,14 @@ flags = flags.split(/[ ,|]+/);
 /**
- * Define option with `flags`, `description` and optional
- * coercion `fn`.
+ * Internal implementation shared by .option() and .requiredOption()
  *
- * The `flags` string should contain both the short and long flags,
- * separated by comma, a pipe or space. The following are all valid
- * all will output this way when `--help` is used.
- *
- *    "-p, --pepper"
- *    "-p|--pepper"
- *    "-p --pepper"
- *
- * Examples:
- *
- *     // simple boolean defaulting to undefined
- *     program.option('-p, --pepper', 'add pepper');
- *
- *     program.pepper
- *     // => undefined
- *
- *     --pepper
- *     program.pepper
- *     // => true
- *
- *     // simple boolean defaulting to true (unless non-negated option is also defined)
- *     program.option('-C, --no-cheese', 'remove cheese');
- *
- *     program.cheese
- *     // => true
- *
- *     --no-cheese
- *     program.cheese
- *     // => false
- *
- *     // required argument
- *     program.option('-C, --chdir <path>', 'change the working directory');
- *
- *     --chdir /tmp
- *     program.chdir
- *     // => "/tmp"
- *
- *     // optional argument
- *     program.option('-c, --cheese [type]', 'add cheese [marble]');
- *
+ * @param {Object} config
  * @param {String} flags
  * @param {String} description
- * @param {Function|*} [fn] or default
+ * @param {Function|*} [fn] - custom option processing function or default vaue
  * @param {*} [defaultValue]
  * @return {Command} for chaining
- * @api public
+ * @api private
  */
 
-Command.prototype.option = function(flags, description, fn, defaultValue) {
+Command.prototype._optionEx = function(config, flags, description, fn, defaultValue) {
   var self = this,
@@ -426,2 +387,3 @@ option = new Option(flags, description),
     name = option.attributeName();
+  option.mandatory = !!config.mandatory;
 
@@ -489,2 +451,76 @@ // default as 3rd arg
 /**
+ * Define option with `flags`, `description` and optional
+ * coercion `fn`.
+ *
+ * The `flags` string should contain both the short and long flags,
+ * separated by comma, a pipe or space. The following are all valid
+ * all will output this way when `--help` is used.
+ *
+ *    "-p, --pepper"
+ *    "-p|--pepper"
+ *    "-p --pepper"
+ *
+ * Examples:
+ *
+ *     // simple boolean defaulting to undefined
+ *     program.option('-p, --pepper', 'add pepper');
+ *
+ *     program.pepper
+ *     // => undefined
+ *
+ *     --pepper
+ *     program.pepper
+ *     // => true
+ *
+ *     // simple boolean defaulting to true (unless non-negated option is also defined)
+ *     program.option('-C, --no-cheese', 'remove cheese');
+ *
+ *     program.cheese
+ *     // => true
+ *
+ *     --no-cheese
+ *     program.cheese
+ *     // => false
+ *
+ *     // required argument
+ *     program.option('-C, --chdir <path>', 'change the working directory');
+ *
+ *     --chdir /tmp
+ *     program.chdir
+ *     // => "/tmp"
+ *
+ *     // optional argument
+ *     program.option('-c, --cheese [type]', 'add cheese [marble]');
+ *
+ * @param {String} flags
+ * @param {String} description
+ * @param {Function|*} [fn] - custom option processing function or default vaue
+ * @param {*} [defaultValue]
+ * @return {Command} for chaining
+ * @api public
+ */
+
+Command.prototype.option = function(flags, description, fn, defaultValue) {
+  return this._optionEx({}, flags, description, fn, defaultValue);
+};
+
+/*
+ * Add a required option which must have a value after parsing. This usually means
+ * the option must be specified on the command line. (Otherwise the same as .option().)
+ *
+ * The `flags` string should contain both the short and long flags, separated by comma, a pipe or space.
+ *
+ * @param {String} flags
+ * @param {String} description
+ * @param {Function|*} [fn] - custom option processing function or default vaue
+ * @param {*} [defaultValue]
+ * @return {Command} for chaining
+ * @api public
+ */
+
+Command.prototype.requiredOption = function(flags, description, fn, defaultValue) {
+  return this._optionEx({ mandatory: true }, flags, description, fn, defaultValue);
+};
+
+/**
  * Allow unknown options on the command line.
@@ -797,2 +833,17 @@ *
 /**
+ * Display an error message if a mandatory option does not have a value.
+ *
+ * @api private
+ */
+
+Command.prototype._checkForMissingMandatoryOptions = function() {
+  const self = this;
+  this.options.forEach((anOption) => {
+    if (anOption.mandatory && (self[anOption.attributeName()] === undefined)) {
+      self.missingMandatoryOptionValue(anOption);
+    }
+  });
+};
+
+/**
  * Parse options from `argv` returning `argv`
@@ -873,2 +924,4 @@ * void of these options.
 
+  this._checkForMissingMandatoryOptions();
+
   return { args: args, unknown: unknownOptions };
@@ -927,2 +980,15 @@ };
 /**
+ * `Option` does not have a value, and is a mandatory option.
+ *
+ * @param {String} option
+ * @api private
+ */
+
+Command.prototype.missingMandatoryOptionValue = function(option) {
+  const message = `error: required option '${option.flags}' not specified`;
+  console.error(message);
+  this._exit(1, 'commander.missingMandatoryOptionValue', message);
+};
+
+/**
  * Unknown option `flag`.
@@ -929,0 +995,0 @@ *

package.json

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

Readme.md

@@ -18,2 +18,3 @@ # Commander.js
     - [Custom option processing](#custom-option-processing)
+    - [Required option](#required-option)
     - [Version option](#version-option)
@@ -246,2 +247,20 @@ - [Commands](#commands)
 
+### Required option
+
+You may specify a required (mandatory) option using `.requiredOption`. The option must be specified on the command line, or by having a default value. The method is otherwise the same as `.option` in format, taking flags and description, and optional default value or custom processing.
+
+```js
+const program = require('commander');
+
+program
+  .requiredOption('-c, --cheese <type>', 'pizza must have cheese');
+
+program.parse(process.argv);
+```
+
+```
+$ pizza
+error: required option '-c, --cheese <type>' not specified
+```
+
 ### Version option
@@ -248,0 +267,0 @@

typings/index.d.ts

@@ -21,4 +21,5 @@ // Type definitions for commander 2.11
     flags: string;
-    required: boolean;
-    optional: boolean;
+    required: boolean; // A value must be supplied when the option is specified.
+    optional: boolean; // A value is optional when the option is specified.
+    mandatory: boolean; // The option must have a value after parsing, which usually means it must be specified on command line.
     bool: boolean;
@@ -191,2 +192,11 @@ short?: string;
     /**
+     * Define a required option, which must have a value after parsing. This usually means
+     * the option must be specified on the command line. (Otherwise the same as .option().)
+     *
+     * The `flags` string should contain both the short and long flags, separated by comma, a pipe or space.
+     */
+    requiredOption(flags: string, description?: string, fn?: ((arg1: any, arg2: any) => void) | RegExp, defaultValue?: any): Command;
+    requiredOption(flags: string, description?: string, defaultValue?: any): Command;
+
+    /**
      * Allow unknown options on the command line.
@@ -193,0 +203,0 @@ *

No alert changes

Improved metrics

Total package byte prevSize

88892

increased by4.55%

Lines of code

1624

increased by4.24%

Number of lines in readme file

655

increased by2.99%

No dependency changes