CHANGELOG.md

@@ -8,6 +8,18 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 <!-- markdownlint-disable MD024 -->
 <!-- markdownlint-disable MD004 -->
 
+## [9.4.1] (2022-09-30)
+
+### Fixed
+
+- `.setOptionValue()` now also clears option source ([#1795])
+- TypeScript: add `implied` to `OptionValueSource` for option values set by using `.implies()` ([#1794])
+- TypeScript : add `undefined` to return type of `.getOptionValueSource()` ([#1794])
+
+### Changed
+
+- additions to README
+
 ## [9.4.0] (2022-07-15)
 
 ### Added
@@ -1095,6 +1107,8 @@ program
 [#1756]: https://github.com/tj/commander.js/pull/1756
 [#1763]: https://github.com/tj/commander.js/pull/1763
 [#1767]: https://github.com/tj/commander.js/pull/1767
+[#1794]: https://github.com/tj/commander.js/pull/1794
+[#1795]: https://github.com/tj/commander.js/pull/1795
 
 <!-- Referenced in 5.x -->
 [#1]: https://github.com/tj/commander.js/issues/1
@@ -1173,6 +1187,7 @@ program
 [#1028]: https://github.com/tj/commander.js/pull/1028
 
 [Unreleased]: https://github.com/tj/commander.js/compare/master...develop
+[9.4.1]: https://github.com/tj/commander.js/compare/v9.4.0...v9.4.1
 [9.4.0]: https://github.com/tj/commander.js/compare/v9.3.0...v9.4.0
 [9.3.0]: https://github.com/tj/commander.js/compare/v9.2.0...v9.3.0
 [9.2.0]: https://github.com/tj/commander.js/compare/v9.1.0...v9.2.0

Readme.md

@@ -330,7 +330,7 @@ For information about possible ambiguous cases, see [options taking varying argu
 
 ### Required option
 
-You may specify a required (mandatory) option using `.requiredOption`. The option must have a value after parsing, usually specified on the command line, or perhaps from a default value (say from environment). The method is otherwise the same as `.option` in format, taking flags and description, and optional default value or custom processing.
+You may specify a required (mandatory) option using `.requiredOption()`. The option must have a value after parsing, usually specified on the command line, or perhaps from a default value (say from environment). The method is otherwise the same as `.option()` in format, taking flags and description, and optional default value or custom processing.
 
 Example file: [options-required.js](./examples/options-required.js)
 
@@ -441,6 +441,8 @@ $ extra --disable-server --port 8000
 error: option '--disable-server' cannot be used with option '-p, --port <number>'
 ```
 
+Specify a required (mandatory) option using the `Option` method `.makeOptionMandatory()`. This matches the `Command` method [.requiredOption()](#required-option).
+
 ### Custom option processing
 
 You may specify a function to do custom processing of option-arguments. The callback function receives two parameters,
@@ -541,6 +543,8 @@ Configuration options can be passed with the call to `.command()` and `.addComma
 remove the command from the generated help output. Specifying `isDefault: true` will run the subcommand if no other
 subcommand is specified ([example](./examples/defaultCommand.js)).
 
+For safety, `.addCommand()` does not automatically copy the inherited settings from the parent command. There is a helper routine `.copyInheritedSettings()` for copying the settings when they are wanted.
+
 ### Command-arguments
 
 For subcommands, you can specify the argument syntax in the call to `.command()` (as shown above). This

lib/command.js

@@ -37,7 +37,7 @@ class Command extends EventEmitter {
     this._scriptPath = null;
     this._name = name || '';
     this._optionValues = {};
-    this._optionValueSources = {}; // default < config < env < cli
+    this._optionValueSources = {}; // default, env, cli etc
     this._storeOptionsAsProperties = false;
     this._actionHandler = null;
     this._executableHandler = false;
@@ -780,32 +780,31 @@ Expecting one of '${allowedValues.join("', '")}'`);
    */
 
   setOptionValue(key, value) {
-    if (this._storeOptionsAsProperties) {
-      this[key] = value;
-    } else {
-      this._optionValues[key] = value;
-    }
-    return this;
+    return this.setOptionValueWithSource(key, value, undefined);
   }
 
   /**
-   * Store option value and where the value came from.
+    * Store option value and where the value came from.
     *
     * @param {string} key
     * @param {Object} value
-    * @param {string} source - expected values are default/config/env/cli
+    * @param {string} source - expected values are default/config/env/cli/implied
     * @return {Command} `this` command for chaining
     */
 
   setOptionValueWithSource(key, value, source) {
-    this.setOptionValue(key, value);
+    if (this._storeOptionsAsProperties) {
+      this[key] = value;
+    } else {
+      this._optionValues[key] = value;
+    }
     this._optionValueSources[key] = source;
     return this;
   }
 
   /**
     * Get source of option value.
-    * Expected values are default | config | env | cli
+    * Expected values are default | config | env | cli | implied
     *
     * @param {string} key
     * @return {string}

lib/option.js

@@ -105,7 +105,9 @@ class Option {
 
   /**
    * Set environment variable to check for option value.
-   * Priority order of option values is default < env < cli
+   *
+   * An environment variable is only used if when processed the current option value is
+   * undefined, or the source of the current value is 'default' or 'config' or 'env'.
    *
    * @param {string} name
    * @return {Option}

package.json

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

tests/options.getset.test.js

@@ -28,7 +28,7 @@ test('when setOptionValueWithSource then value returned by opts', () => {
   const cheeseValue = 'blue';
   program
     .option('--cheese [type]', 'cheese type')
-    .setOptionValue('cheese', cheeseValue);
+    .setOptionValueWithSource('cheese', cheeseValue, 'cli');
   expect(program.opts().cheese).toBe(cheeseValue);
 });
 
@@ -57,3 +57,12 @@ test('when option value parsed from cli then option source is cli', () => {
   program.parse(['--foo'], { from: 'user' });
   expect(program.getOptionValueSource('foo')).toBe('cli');
 });
+
+test('when setOptionValue then clears previous source', () => {
+  const program = new commander.Command();
+  program
+    .option('--foo', 'description', 'default value');
+  expect(program.getOptionValueSource('foo')).toBe('default');
+  program.setOptionValue('foo', 'bar');
+  expect(program.getOptionValueSource('foo')).toBeUndefined();
+});

typings/index.d.ts

@@ -144,7 +144,9 @@ export class Option {
 
   /**
    * Set environment variable to check for option value.
-   * Priority order of option values is default < env < cli
+   *
+   * An environment variables is only used if when processed the current option value is
+   * undefined, or the source of the current value is 'default' or 'config' or 'env'.
    */
   env(name: string): this;
 
@@ -266,7 +268,7 @@ export interface OutputConfiguration {
 
 export type AddHelpTextPosition = 'beforeAll' | 'before' | 'after' | 'afterAll';
 export type HookEvent = 'preSubcommand' | 'preAction' | 'postAction';
-export type OptionValueSource = 'default' | 'env' | 'config' | 'cli';
+export type OptionValueSource = 'default' | 'config' | 'env' | 'cli' | 'implied';
 
 export interface OptionValues {
   [key: string]: any;
@@ -595,7 +597,7 @@ export class Command {
   /**
    * Retrieve option value source.
    */
-  getOptionValueSource(key: string): OptionValueSource;
+  getOptionValueSource(key: string): OptionValueSource | undefined;
 
   /**
    * Alter parsing of short flags with optional values.

typings/index.test-d.ts

@@ -172,7 +172,7 @@ expectType<commander.Command>(program.setOptionValue('example', true));
 expectType<commander.Command>(program.setOptionValueWithSource('example', [], 'cli'));
 
 // getOptionValueSource
-expectType<commander.OptionValueSource>(program.getOptionValueSource('example'));
+expectType<commander.OptionValueSource | undefined>(program.getOptionValueSource('example'));
 
 // combineFlagAndOptionalValue
 expectType<commander.Command>(program.combineFlagAndOptionalValue());