From 1ae63aa5174d886568fdbc2c20eeda0c989703ab Mon Sep 17 00:00:00 2001
From: Christopher Hiller <boneskull@boneskull.com>
Date: Wed, 9 Sep 2020 17:21:49 -0700
Subject: [PATCH 01/14] util: add util.parseArgs()

Add a function, `util.parseArgs()`, which accepts an array of
arguments and returns a parsed object representation thereof.

Ref: https://github.com/nodejs/tooling/issues/19
---
 doc/api/util.md                         | 103 +++++++++++++++
 lib/internal/util/parse_args.js         | 121 ++++++++++++++++++
 lib/util.js                             |   2 +
 node.gyp                                |   1 +
 test/parallel/test-bootstrap-modules.js |   1 +
 test/parallel/test-util-parseargs.js    | 160 ++++++++++++++++++++++++
 6 files changed, 388 insertions(+)
 create mode 100644 lib/internal/util/parse_args.js
 create mode 100644 test/parallel/test-util-parseargs.js

diff --git a/doc/api/util.md b/doc/api/util.md
index 6b857a027f39ef..b6758a345a59fc 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -946,6 +946,107 @@ Otherwise, returns `false`.
 See [`assert.deepStrictEqual()`][] for more information about deep strict
 equality.
 
+## `util.parseArgs([argv[, options]])`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `argv` {Array<string>|Object} (Optional) Array of argument strings; defaults
+  to [`process.argv.slice(2)`](process_argv). If an Object, the default is used,
+  and this parameter is considered to be the `options` parameter.
+* `options` {Object} (Optional) The `options` parameter, if present, is an
+  object supporting the following property:
+  * `expectsValue` {Array<string>|string} (Optional) One or more argument
+    strings which _expect a value_ when present
+* Returns: {Object} An object having properties corresponding to parsed Options
+  and Flags, and a property `_` containing Positionals
+
+The `util.parseArgs` function parses command-line arguments from an array of
+strings and returns an object representation.
+
+Example using [`process.argv`][]:
+
+```js
+// script.js
+// called via `node script.js --foo bar baz`
+const argv = util.parseArgs();
+
+// argv.foo === true
+if (argv.foo) {
+  console.log(argv._); // prints [ 'bar', 'baz' ]
+}
+```
+
+Example using a custom `argv` and the `expectsValue` option:
+
+```js
+const argv = util.parseArgs(
+  ['--foo', 'bar', 'baz'],
+  { expectsValue: ['foo'] }
+);
+
+// argv.foo === 'bar'
+if (argv.foo === 'bar') {
+  console.log(argv._); // prints [ 'baz' ]
+}
+```
+
+[`ERR_INVALID_ARG_TYPE`][] will be thrown if the `argv` parameter is not an
+Array.
+
+Arguments fall into one of three catgories:
+
+* _Flags_, which begin with one or more dashes (`-`), and _do not_ have an
+  associated string value (e.g., `node app.js --verbose`)
+  * These will be parsed automatically; you do not need to "declare" them
+  * The Flag _name_ is the string following the prefix of one-or-more dashes,
+    e.g., the name of `--foo` is `foo`
+  * Flag names become property names in the returned object
+  * When appearing _once_ in the array, the value of the property will be `true`
+  * When _repeated_ in the array, the value of the property becomes a count of
+    repetitions (e.g., `['-v', '-v' '-v']` results in `{ v: 3 }`)
+* _Options_, declared by `expectsValue`, which begin with one or more dashes,
+  and _do_ have an associated value (e.g., `node app.js --require script.js`)
+  * Use the `expectsValue` option to `util.parseArgs` to declare Options
+  * The Option _name_ is the string following the prefix of one-or-more dashes,
+    e.g., the name of `--foo` is `foo`
+  * The Option _value_ is the next string following the name, e.g., the Option
+    value of `['--foo' 'bar']` is `bar`
+  * Option values may be provided _with or without_ a `=` separator (e.g.,
+    `['--require=script.js']` is equivalent to `['--require', 'script.js']`)
+  * An Option value is considered "missing" and is results in `true` when:
+    * A `=` does not separate the Option name from its value (e.g., `--foo bar`)
+      _and_ the following argument begins with a dash (e.g., `['--foo',
+      '--bar']`), _OR_
+    * The array ends with the Option name (e.g., `['--foo']`)
+  * When repeated, values are concatenated into an Array; unlike Flags, they _do
+    not_ become a numeric count
+  * When an Option name appears in the Array (or string) of `expectsValue`, and
+    does _not_ appear in the `argv` array, the resulting object _will not_
+    contain a property with this Option name (e.g.,
+    `util.parseArgs(['--bar'], { expectsValue: 'foo' })` will result in
+    `{bar: true, _: [] }`
+* _Positionals_ (or "positional arguments"), which _do not_ begin with one or
+  more dashes (e.g., `['script.js']`), _or_ every item in the `argv` Array
+  following a `--` (e.g., `['--', 'script.js']`)
+  * Positionals appear in the Array property `_` of the returned object
+  * The `_` property will _always_ be present and an Array, even if empty
+  * If present in the `argv` Array, `--` is discarded and is omitted from the
+    returned object
+  * Positionals will _always_ be parsed verbatim (e.g., `['--', '--foo']` will
+    result in an object of `{_: ['--foo']}`)
+
+A Flag or Option with having the name `_` will be ignored. If it was declared
+as an Option (via the `expectsValue` option), its value will be ignored as well.
+
+`util.parseArgs` does not consider "short" arguments (e.g., `-v`) to be
+different than "long" arguments (e.g., `--verbose`).  Furthermore, it does not
+allow concatenation of short arguments (e.g., `-v -D` cannot be expressed as
+`-vD`).
+
+Conversion to/from "camelCase" occurs; a Flag or Option name of `no-color`
+results in an object with a `no-color` property.
+
 ## `util.promisify(original)`
 <!-- YAML
 added: v8.0.0
@@ -2497,8 +2598,10 @@ util.log('Timestamped message.');
 [compare function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Parameters
 [constructor]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/constructor
 [default sort]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort
+[`ERR_INVALID_ARG_TYPE`]: errors.html#ERR_INVALID_ARG_TYPE
 [global symbol registry]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/for
 [list of deprecated APIS]: deprecations.html#deprecations_list_of_deprecated_apis
 [`napi_create_external()`]: n-api.html#n_api_napi_create_external
+[`process.argv`]: process.html#process_process_argv
 [semantically incompatible]: https://github.com/nodejs/node/issues/4179
 [util.inspect.custom]: #util_util_inspect_custom
diff --git a/lib/internal/util/parse_args.js b/lib/internal/util/parse_args.js
new file mode 100644
index 00000000000000..5839122cb479a4
--- /dev/null
+++ b/lib/internal/util/parse_args.js
@@ -0,0 +1,121 @@
+'use strict';
+
+const {
+  ArrayIsArray,
+  ArrayPrototypePush,
+  ArrayPrototypeSlice,
+  Number,
+  SafeSet,
+  StringPrototypeReplace,
+  StringPrototypeSplit,
+  StringPrototypeStartsWith,
+} = primordials;
+const { ERR_INVALID_ARG_TYPE } = require('internal/errors').codes;
+
+/**
+ * Returns an Object representation of command-line arguments to a script.
+ *
+ * Default behavior:
+ * - All arguments are considered "boolean flags"; in the returned
+ *   object, the key is the argument (if present), and the value will be `true`.
+ * - Uses `process.argv.slice(2)`, but can accept an explicit array of strings.
+ * - Argument(s) specified in `opts.expectsValue` will have `string` values
+ *   instead of `true`; the subsequent item in the `argv` array will be consumed
+ *   if a `=` is not used.
+ * - If `=` is present, the value will be boolean if and only if the RHS of the
+ *   string is one of string `true` or `false`
+ * - "Bare" arguments are those which do not begin with a `-` or `--` and those
+ *   after a bare `--`; these will be returned as items of the `_` array
+ * - The `_` array will always be present, even if empty.
+ * - Repeated arguments are combined into an array
+ * @param {string[]} [argv=process.argv.slice(2)] - Array of script arguments as
+ * strings
+ * @param {Object} [options] - Options
+ * @param {string[]|string} [opts.expectsValue] - Argument(s) listed here expect
+ * a value
+ * @example
+ * parseArgs(['--foo', '--bar']) // {foo: true, bar: true, _: []}
+ * parseArgs(['--foo', '-b']) // {foo: true, b: true, _: []}
+ * parseArgs(['---foo']) // {foo: true, _: []}
+ * parseArgs(['--foo=bar']) // {foo: true, _: []}
+ * parseArgs(['--foo', 'bar']) // {foo: true, _: ['bar']}
+ * parseArgs(['--foo', 'bar'], {expectsValue: 'foo'}) // {foo: 'bar', _: []}
+ * parseArgs(['foo']) // {_: ['foo']}
+ * parseArgs(['--foo', '--', '--bar']) // {foo: true, _: ['--bar']}
+ * parseArgs(['--foo=bar', '--foo=baz']) // {foo: ['bar', 'baz'], _: []}
+ * parseArgs(['--foo', '--foo']) // {foo: true, _: []}
+ * pasreArgs(['--foo=true']) // {foo: true, _: []}
+ * parseArgs(['--foo=false']) // {foo: false, _: [])}
+ * parseArgs(['--foo=true', '--foo=false']) // {foo: false, _: [])}
+ * parseArgs(['--foo', 'true']) // {foo: true, _: ['true']}
+ * parseArgs(['--foo', 'true'], {expectsValue: ['foo']}) // {foo: true, _: []}
+ */
+const parseArgs = (
+  argv = ArrayPrototypeSlice(process.argv, 2),
+  options = { expectsValue: [] }
+) => {
+  if (!ArrayIsArray(argv)) {
+    options = argv;
+    argv = ArrayPrototypeSlice(process.argv, 2);
+  }
+  if (typeof options !== 'object' || options === null) {
+    throw new ERR_INVALID_ARG_TYPE(
+      'options',
+      'object',
+      options);
+  }
+  if (typeof options.expectsValue === 'string') {
+    options.expectsValue = [options.expectsValue];
+  }
+  const expectsValue = new SafeSet(options.expectsValue || []);
+  const result = { _: [] };
+
+  let pos = 0;
+  while (true) {
+    const arg = argv[pos];
+    if (arg === undefined) {
+      return result;
+    }
+    if (StringPrototypeStartsWith(arg, '-')) {
+      // Everything after a bare '--' is considered a positional argument
+      // and is returned verbatim
+      if (arg === '--') {
+        ArrayPrototypePush(result._, ...ArrayPrototypeSlice(argv, ++pos));
+        return result;
+      }
+      // Any number of leading dashes are allowed
+      const argParts = StringPrototypeSplit(StringPrototypeReplace(arg, /^-+/, ''), '=');
+      const lhs = argParts[0];
+      let rhs = argParts[1];
+
+      if (expectsValue.has(lhs)) {
+        // Consume the next item in the array if `=` was not used
+        // and the next item is not itself a flag or option
+        if (rhs === undefined) {
+          rhs = StringPrototypeStartsWith(argv[pos + 1], '-') || argv[++pos];
+        }
+
+        if (lhs !== '_') {
+          if (result[lhs] === undefined) {
+            result[lhs] = rhs;
+          } else if (ArrayIsArray(result[lhs])) {
+            ArrayPrototypePush(result[lhs], rhs);
+          } else {
+            result[lhs] = [result[lhs], rhs];
+          }
+        }
+      } else if (lhs !== '_') {
+        // In the case of args where we did not expect a value, the value is
+        // `true` unless there are multiple, at which point it becomes a count.
+        result[lhs] = result[lhs] === undefined || Number(result[lhs]) + 1;
+      }
+    } else if (arg !== '_') {
+      ArrayPrototypePush(result._, arg);
+    }
+    pos++;
+  }
+};
+
+module.exports = {
+  parseArgs
+};
diff --git a/lib/util.js b/lib/util.js
index 1414c0d11d58a8..2492a15c13f02c 100644
--- a/lib/util.js
+++ b/lib/util.js
@@ -54,6 +54,7 @@ const { validateNumber } = require('internal/validators');
 const { TextDecoder, TextEncoder } = require('internal/encoding');
 const { isBuffer } = require('buffer').Buffer;
 const types = require('internal/util/types');
+const { parseArgs } = require('internal/util/parse_args');
 
 const {
   deprecate,
@@ -270,6 +271,7 @@ module.exports = {
   isFunction,
   isPrimitive,
   log,
+  parseArgs,
   promisify,
   TextDecoder,
   TextEncoder,
diff --git a/node.gyp b/node.gyp
index 5da3ae61bcba14..e9ed129743dfe1 100644
--- a/node.gyp
+++ b/node.gyp
@@ -218,6 +218,7 @@
       'lib/internal/util/debuglog.js',
       'lib/internal/util/inspect.js',
       'lib/internal/util/inspector.js',
+      'lib/internal/util/parse_args.js',
       'lib/internal/util/types.js',
       'lib/internal/http2/core.js',
       'lib/internal/http2/compat.js',
diff --git a/test/parallel/test-bootstrap-modules.js b/test/parallel/test-bootstrap-modules.js
index 735f2e6394bd20..3eed9e3a3aca94 100644
--- a/test/parallel/test-bootstrap-modules.js
+++ b/test/parallel/test-bootstrap-modules.js
@@ -80,6 +80,7 @@ const expectedModules = new Set([
   'NativeModule internal/util',
   'NativeModule internal/util/debuglog',
   'NativeModule internal/util/inspect',
+  'NativeModule internal/util/parse_args',
   'NativeModule internal/util/types',
   'NativeModule internal/validators',
   'NativeModule internal/vm/module',
diff --git a/test/parallel/test-util-parseargs.js b/test/parallel/test-util-parseargs.js
new file mode 100644
index 00000000000000..9be5987e51a629
--- /dev/null
+++ b/test/parallel/test-util-parseargs.js
@@ -0,0 +1,160 @@
+'use strict';
+
+const { invalidArgTypeHelper } = require('../common');
+const assert = require('assert');
+const { format, parseArgs } = require('util');
+
+{
+  const data = new Map([
+    [
+      { argv: ['--foo', '--bar'] },
+      { foo: true, bar: true, _: [] }
+    ],
+    [
+      { argv: ['--foo', '-b'] },
+      { foo: true, b: true, _: [] }
+    ],
+    [
+      { argv: ['---foo'] },
+      { foo: true, _: [] }
+    ],
+    [
+      { argv: ['--foo=bar'] },
+      { foo: true, _: [] }
+    ],
+    [
+      { argv: ['--foo=bar'], opts: { expectsValue: ['foo'] } },
+      { foo: 'bar', _: [] }
+    ],
+    [
+      { argv: ['--foo', 'bar'] },
+      { foo: true, _: ['bar'] }
+    ],
+    [
+      { argv: ['--foo', 'bar'], opts: { expectsValue: 'foo' } },
+      { foo: 'bar', _: [] }
+    ],
+    [
+      { argv: ['foo'] },
+      { _: ['foo'] }
+    ],
+    [
+      { argv: ['--foo', '--', '--bar'] },
+      { foo: true, _: ['--bar'] }
+    ],
+    [
+      { argv: ['--foo=bar', '--foo=baz'], opts: { expectsValue: 'foo' } },
+      { foo: ['bar', 'baz'], _: [] }
+    ],
+    [
+      { argv: ['--foo', '--foo'] },
+      { foo: 2, _: [] }
+    ],
+    [
+      { argv: ['--foo=true'] },
+      { foo: true, _: [] }
+    ],
+    [
+      { argv: ['--foo=false'] },
+      { foo: true, _: [] }
+    ],
+    [
+      { argv: ['--foo', 'true'] },
+      { foo: true, _: ['true'] }
+    ],
+    [
+      { argv: ['--foo', 'true'], opts: { expectsValue: ['foo'] } },
+      { foo: 'true', _: [] }
+    ],
+    [
+      { argv: ['--foo', 'false', 'false'], opts: { expectsValue: ['foo'] } },
+      { foo: 'false', _: ['false'] }
+    ],
+    [
+      { argv: ['--foo=true', '--foo=false'] },
+      { foo: 2, _: [] }
+    ],
+    [
+      { argv: ['--foo', 'true', '--foo', 'false'] },
+      { foo: 2, _: ['true', 'false'] }
+    ],
+    [
+      { argv: ['--foo', 'true', '--foo', 'false'],
+        opts: { expectsValue: 'foo' } },
+      { foo: ['true', 'false'], _: [] }
+    ],
+    [
+      { argv: ['--foo', 'true', '--foo=false'],
+        opts: { expectsValue: 'foo' } },
+      { foo: ['true', 'false'], _: [] }
+    ],
+    [
+      { argv: ['--foo', 'true', '--foo=false'] },
+      { foo: 2, _: ['true'] }
+    ],
+    [
+      {
+        argv: ['--foo', 'bar', '--foo', 'baz'],
+        opts: { expectsValue: ['foo'] }
+      },
+      { foo: ['bar', 'baz'], _: [] }
+    ],
+    [
+      { argv: ['--foo', '--bar'], opts: { expectsValue: 'foo' } },
+      { foo: true, bar: true, _: [] }
+    ],
+    [
+      { argv: ['--foo=--bar'], opts: { expectsValue: 'foo' } },
+      { foo: '--bar', _: [] }
+    ],
+    [
+      { argv: ['-_'] },
+      { _: [] }
+    ],
+    [
+      { argv: ['--_=bar'], opts: { expectsValue: '_' } },
+      { _: [] }
+    ],
+    [
+      { argv: ['--_', 'bar'], opts: { expectsValue: '_' } },
+      { _: [] }
+    ]
+  ]);
+
+  data.forEach((output, input) => {
+    const { argv, opts } = input;
+    assert.deepStrictEqual(
+      parseArgs(argv, opts),
+      output,
+      format('%o does not parse to %o', input, output)
+    );
+  });
+}
+
+{
+  // Use of `process.argv.slice(2)` as default `argv` value
+  const originalArgv = process.argv;
+  process.argv = [process.execPath, __filename, '--foo', 'bar'];
+  try {
+    assert.deepStrictEqual(parseArgs(), { foo: true, _: ['bar'] });
+    assert.deepStrictEqual(
+      parseArgs({ expectsValue: 'foo' }), { foo: 'bar', _: [] }
+    );
+  } finally {
+    process.argv = originalArgv;
+  }
+}
+
+{
+  // error checking
+  const value = 'strings not allowed';
+  assert.throws(() => {
+    parseArgs(value);
+  }, {
+    code: 'ERR_INVALID_ARG_TYPE',
+    name: 'TypeError',
+    message:
+      'The "options" argument must be of type object.' +
+      invalidArgTypeHelper(value)
+  });
+}

From b180e2af4c68156f90f5e7ce04caee4dcac05a5e Mon Sep 17 00:00:00 2001
From: Christopher Hiller <boneskull@boneskull.com>
Date: Thu, 10 Sep 2020 17:08:10 -0700
Subject: [PATCH 02/14] review changes

- rename `expectsValue` to `optionsWithValue`
- output an object with props `options` and `positionals` instead of magic `_`
- add `multiOptions` option, which results in arrays when parsed
- remove "count" functionality in lieu of `multiOptions`
- update examples in docstring
- update tests
- update docs
---
 doc/api/util.md                      |  39 ++++++---
 lib/internal/util/parse_args.js      | 117 ++++++++++++++++-----------
 test/parallel/test-util-parseargs.js | 113 ++++++++++++++++----------
 3 files changed, 169 insertions(+), 100 deletions(-)

diff --git a/doc/api/util.md b/doc/api/util.md
index b6758a345a59fc..d9f674abfd994d 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -956,10 +956,14 @@ added: REPLACEME
   and this parameter is considered to be the `options` parameter.
 * `options` {Object} (Optional) The `options` parameter, if present, is an
   object supporting the following property:
-  * `expectsValue` {Array<string>|string} (Optional) One or more argument
+  * `optionsWithValue` {Array<string>|string} (Optional) One or more argument
     strings which _expect a value_ when present
-* Returns: {Object} An object having properties corresponding to parsed Options
-  and Flags, and a property `_` containing Positionals
+  * `multiOptions` {Array<string>|string} (Optional) One or more argument
+    strings which can be appear multiple times in `argv` and will be
+    concatenated into an array
+* Returns: {Object} An object having properties:
+  * `options`, an Object with properties and values corresponding to parsed Options and Flags
+  * `positionals`, an Array containing containing Positionals
 
 The `util.parseArgs` function parses command-line arguments from an array of
 strings and returns an object representation.
@@ -973,24 +977,35 @@ const argv = util.parseArgs();
 
 // argv.foo === true
 if (argv.foo) {
-  console.log(argv._); // prints [ 'bar', 'baz' ]
+  console.log(argv.positionals); // prints [ 'bar', 'baz' ]
 }
 ```
 
-Example using a custom `argv` and the `expectsValue` option:
+Example using a custom `argv` and the `optionsWithValue` option:
 
 ```js
 const argv = util.parseArgs(
   ['--foo', 'bar', 'baz'],
-  { expectsValue: ['foo'] }
+  { optionsWithValue: ['foo'] }
 );
 
 // argv.foo === 'bar'
 if (argv.foo === 'bar') {
-  console.log(argv._); // prints [ 'baz' ]
+  console.log(argv.positionals); // prints [ 'baz' ]
 }
 ```
 
+Example using custom `argv`, `optionsWithValue`, and the `multiOptions` option:
+
+```js
+const argv = util.parseArgs(
+  ['--foo', 'bar', '--foo', 'baz'],
+  { optionsWithValue: 'foo', multiOptions: 'foo' }
+);
+
+console.log(argv.options.bar); // prints [ 'bar', 'baz' ]
+```
+
 [`ERR_INVALID_ARG_TYPE`][] will be thrown if the `argv` parameter is not an
 Array.
 
@@ -1005,9 +1020,9 @@ Arguments fall into one of three catgories:
   * When appearing _once_ in the array, the value of the property will be `true`
   * When _repeated_ in the array, the value of the property becomes a count of
     repetitions (e.g., `['-v', '-v' '-v']` results in `{ v: 3 }`)
-* _Options_, declared by `expectsValue`, which begin with one or more dashes,
+* _Options_, declared by `optionsWithValue`, which begin with one or more dashes,
   and _do_ have an associated value (e.g., `node app.js --require script.js`)
-  * Use the `expectsValue` option to `util.parseArgs` to declare Options
+  * Use the `optionsWithValue` option to `util.parseArgs` to declare Options
   * The Option _name_ is the string following the prefix of one-or-more dashes,
     e.g., the name of `--foo` is `foo`
   * The Option _value_ is the next string following the name, e.g., the Option
@@ -1021,10 +1036,10 @@ Arguments fall into one of three catgories:
     * The array ends with the Option name (e.g., `['--foo']`)
   * When repeated, values are concatenated into an Array; unlike Flags, they _do
     not_ become a numeric count
-  * When an Option name appears in the Array (or string) of `expectsValue`, and
+  * When an Option name appears in the Array (or string) of `optionsWithValue`, and
     does _not_ appear in the `argv` array, the resulting object _will not_
     contain a property with this Option name (e.g.,
-    `util.parseArgs(['--bar'], { expectsValue: 'foo' })` will result in
+    `util.parseArgs(['--bar'], { optionsWithValue: 'foo' })` will result in
     `{bar: true, _: [] }`
 * _Positionals_ (or "positional arguments"), which _do not_ begin with one or
   more dashes (e.g., `['script.js']`), _or_ every item in the `argv` Array
@@ -1037,7 +1052,7 @@ Arguments fall into one of three catgories:
     result in an object of `{_: ['--foo']}`)
 
 A Flag or Option with having the name `_` will be ignored. If it was declared
-as an Option (via the `expectsValue` option), its value will be ignored as well.
+as an Option (via the `optionsWithValue` option), its value will be ignored as well.
 
 `util.parseArgs` does not consider "short" arguments (e.g., `-v`) to be
 different than "long" arguments (e.g., `--verbose`).  Furthermore, it does not
diff --git a/lib/internal/util/parse_args.js b/lib/internal/util/parse_args.js
index 5839122cb479a4..3bd6cdfd15ce99 100644
--- a/lib/internal/util/parse_args.js
+++ b/lib/internal/util/parse_args.js
@@ -13,46 +13,62 @@ const {
 const { ERR_INVALID_ARG_TYPE } = require('internal/errors').codes;
 
 /**
- * Returns an Object representation of command-line arguments to a script.
+ * Returns an Object representation of command-line arguments.
  *
  * Default behavior:
  * - All arguments are considered "boolean flags"; in the returned
  *   object, the key is the argument (if present), and the value will be `true`.
  * - Uses `process.argv.slice(2)`, but can accept an explicit array of strings.
- * - Argument(s) specified in `opts.expectsValue` will have `string` values
+ * - Argument(s) specified in `opts.optionsWithValue` will have `string` values
  *   instead of `true`; the subsequent item in the `argv` array will be consumed
  *   if a `=` is not used.
  * - If `=` is present, the value will be boolean if and only if the RHS of the
  *   string is one of string `true` or `false`
  * - "Bare" arguments are those which do not begin with a `-` or `--` and those
  *   after a bare `--`; these will be returned as items of the `_` array
- * - The `_` array will always be present, even if empty.
+ * - The `positionals` array will always be present, even if empty.
+ * - The `options` Object will always be present, even if empty.
  * - Repeated arguments are combined into an array
  * @param {string[]} [argv=process.argv.slice(2)] - Array of script arguments as
  * strings
  * @param {Object} [options] - Options
- * @param {string[]|string} [opts.expectsValue] - Argument(s) listed here expect
- * a value
+ * @param {string[]|string} [opts.optionsWithValue] - This argument (or
+ * arguments) expect a value
+ * @param {string[]|string} [opts.multiOptions] - This argument (or arguments)
+ * can be specified multiple times and its values will be concatenated into
+ * an array
  * @example
- * parseArgs(['--foo', '--bar']) // {foo: true, bar: true, _: []}
- * parseArgs(['--foo', '-b']) // {foo: true, b: true, _: []}
- * parseArgs(['---foo']) // {foo: true, _: []}
- * parseArgs(['--foo=bar']) // {foo: true, _: []}
- * parseArgs(['--foo', 'bar']) // {foo: true, _: ['bar']}
- * parseArgs(['--foo', 'bar'], {expectsValue: 'foo'}) // {foo: 'bar', _: []}
- * parseArgs(['foo']) // {_: ['foo']}
- * parseArgs(['--foo', '--', '--bar']) // {foo: true, _: ['--bar']}
- * parseArgs(['--foo=bar', '--foo=baz']) // {foo: ['bar', 'baz'], _: []}
- * parseArgs(['--foo', '--foo']) // {foo: true, _: []}
- * pasreArgs(['--foo=true']) // {foo: true, _: []}
- * parseArgs(['--foo=false']) // {foo: false, _: [])}
- * parseArgs(['--foo=true', '--foo=false']) // {foo: false, _: [])}
- * parseArgs(['--foo', 'true']) // {foo: true, _: ['true']}
- * parseArgs(['--foo', 'true'], {expectsValue: ['foo']}) // {foo: true, _: []}
+ * parseArgs(['--foo', '--bar'])
+ *   // {options: { foo: true, bar: true }, positionals: []}
+ * parseArgs(['--foo', '-b'])
+ *   // {options: { foo: true, b: true }, positionals: []}
+ * parseArgs(['---foo'])
+ *   // {options: { foo: true }, positionals: []}
+ * parseArgs(['--foo=bar'])
+ *   // {options: { foo: true }, positionals: []}
+ * parseArgs([--foo', 'bar'])
+ *   // {options: {foo: true}, positionals: ['bar']}
+ * parseArgs(['--foo', 'bar'], {optionsWithValue: 'foo'})
+ *   // {options: {foo: 'bar'}, positionals: []}
+ * parseArgs(['foo'])
+ *   // {options: {}, positionals: ['foo']}
+ * parseArgs(['--foo', '--', '--bar'])
+ *   // {options: {foo: true}, positionals: ['--bar']}
+ * parseArgs(['--foo=bar', '--foo=baz'])
+ *   // {options: {foo: true}, positionals: []}
+ * parseArgs(['--foo=bar', '--foo=baz'], {optionsWithValue: 'foo'})
+ *   // {options: {foo: 'baz'}, positionals: []}
+ * parseArgs(['--foo=bar', '--foo=baz'], {
+ *   optionsWithValue: 'foo', multiOptions: 'foo'
+ * }) // {options: {foo: ['bar', 'baz']}, positionals: []}
+ * parseArgs(['--foo', '--foo'])
+ *   // {options: {foo: true}, positionals: []}
+ * parseArgs(['--foo', '--foo'], {multiOptions: ['foo']})
+ *   // {options: {foo: [true, true]}, positionals: []}
  */
 const parseArgs = (
   argv = ArrayPrototypeSlice(process.argv, 2),
-  options = { expectsValue: [] }
+  options = { optionsWithValue: [] }
 ) => {
   if (!ArrayIsArray(argv)) {
     options = argv;
@@ -64,11 +80,15 @@ const parseArgs = (
       'object',
       options);
   }
-  if (typeof options.expectsValue === 'string') {
-    options.expectsValue = [options.expectsValue];
+  if (typeof options.optionsWithValue === 'string') {
+    options.optionsWithValue = [options.optionsWithValue];
   }
-  const expectsValue = new SafeSet(options.expectsValue || []);
-  const result = { _: [] };
+  if (typeof options.multiOptions === 'string') {
+    options.multiOptions = [options.multiOptions];
+  }
+  const optionsWithValue = new SafeSet(options.optionsWithValue || []);
+  const multiOptions = new SafeSet(options.multiOptions || []);
+  const result = { positionals: [], options: {} };
 
   let pos = 0;
   while (true) {
@@ -80,37 +100,40 @@ const parseArgs = (
       // Everything after a bare '--' is considered a positional argument
       // and is returned verbatim
       if (arg === '--') {
-        ArrayPrototypePush(result._, ...ArrayPrototypeSlice(argv, ++pos));
+        ArrayPrototypePush(
+          result.positionals, ...ArrayPrototypeSlice(argv, ++pos)
+        );
         return result;
       }
       // Any number of leading dashes are allowed
       const argParts = StringPrototypeSplit(StringPrototypeReplace(arg, /^-+/, ''), '=');
-      const lhs = argParts[0];
-      let rhs = argParts[1];
+      const optionName = argParts[0];
+      let optionValue = argParts[1];
 
-      if (expectsValue.has(lhs)) {
-        // Consume the next item in the array if `=` was not used
-        // and the next item is not itself a flag or option
-        if (rhs === undefined) {
-          rhs = StringPrototypeStartsWith(argv[pos + 1], '-') || argv[++pos];
+      // Consume the next item in the array if `=` was not used
+      // and the next item is not itself a flag or option
+      if (optionsWithValue.has(optionName)) {
+        if (optionValue === undefined) {
+          optionValue = StringPrototypeStartsWith(argv[pos + 1], '-') ||
+              argv[++pos];
         }
+      } else {
+        optionValue = true;
+      }
 
-        if (lhs !== '_') {
-          if (result[lhs] === undefined) {
-            result[lhs] = rhs;
-          } else if (ArrayIsArray(result[lhs])) {
-            ArrayPrototypePush(result[lhs], rhs);
-          } else {
-            result[lhs] = [result[lhs], rhs];
-          }
+      if (multiOptions.has(optionName)) {
+        // Consume the next item in the array if `=` was not used
+        // and the next item is not itself a flag or option
+        if (result.options[optionName] === undefined) {
+          result.options[optionName] = [optionValue];
+        } else {
+          ArrayPrototypePush(result.options[optionName], optionValue);
         }
-      } else if (lhs !== '_') {
-        // In the case of args where we did not expect a value, the value is
-        // `true` unless there are multiple, at which point it becomes a count.
-        result[lhs] = result[lhs] === undefined || Number(result[lhs]) + 1;
+      } else {
+        result.options[optionName] = optionValue;
       }
-    } else if (arg !== '_') {
-      ArrayPrototypePush(result._, arg);
+    } else {
+      ArrayPrototypePush(result.positionals, arg);
     }
     pos++;
   }
diff --git a/test/parallel/test-util-parseargs.js b/test/parallel/test-util-parseargs.js
index 9be5987e51a629..c516f0b280b9a4 100644
--- a/test/parallel/test-util-parseargs.js
+++ b/test/parallel/test-util-parseargs.js
@@ -8,116 +8,143 @@ const { format, parseArgs } = require('util');
   const data = new Map([
     [
       { argv: ['--foo', '--bar'] },
-      { foo: true, bar: true, _: [] }
+      { options: { foo: true, bar: true }, positionals: [] }
     ],
     [
       { argv: ['--foo', '-b'] },
-      { foo: true, b: true, _: [] }
+      { options: { foo: true, b: true }, positionals: [] }
     ],
     [
       { argv: ['---foo'] },
-      { foo: true, _: [] }
+      { options: { foo: true }, positionals: [] }
     ],
     [
       { argv: ['--foo=bar'] },
-      { foo: true, _: [] }
+      { options: { foo: true }, positionals: [] }
     ],
     [
-      { argv: ['--foo=bar'], opts: { expectsValue: ['foo'] } },
-      { foo: 'bar', _: [] }
+      { argv: ['--foo=bar'], opts: { optionsWithValue: ['foo'] } },
+      { options: { foo: 'bar' }, positionals: [] }
     ],
     [
       { argv: ['--foo', 'bar'] },
-      { foo: true, _: ['bar'] }
+      { options: { foo: true }, positionals: ['bar'] }
     ],
     [
-      { argv: ['--foo', 'bar'], opts: { expectsValue: 'foo' } },
-      { foo: 'bar', _: [] }
+      { argv: ['--foo', 'bar'], opts: { optionsWithValue: 'foo' } },
+      { options: { foo: 'bar' }, positionals: [] }
     ],
     [
       { argv: ['foo'] },
-      { _: ['foo'] }
+      { options: {}, positionals: ['foo'] }
     ],
     [
       { argv: ['--foo', '--', '--bar'] },
-      { foo: true, _: ['--bar'] }
+      { options: { foo: true }, positionals: ['--bar'] }
     ],
     [
-      { argv: ['--foo=bar', '--foo=baz'], opts: { expectsValue: 'foo' } },
-      { foo: ['bar', 'baz'], _: [] }
+      { argv: ['--foo=bar', '--foo=baz'], opts: { optionsWithValue: 'foo' } },
+      { options: { foo: 'baz' }, positionals: [] }
+    ],
+    [
+      {
+        argv: ['--foo=bar', '--foo=baz'],
+        opts: { optionsWithValue: 'foo', multiOptions: 'foo' }
+      },
+      { options: { foo: ['bar', 'baz'] }, positionals: [] }
     ],
     [
       { argv: ['--foo', '--foo'] },
-      { foo: 2, _: [] }
+      { options: { foo: true }, positionals: [] }
+    ],
+    [
+      { argv: ['--foo', '--foo'], opts: { multiOptions: 'foo' } },
+      { options: { foo: [true, true] }, positionals: [] }
     ],
     [
       { argv: ['--foo=true'] },
-      { foo: true, _: [] }
+      { options: { foo: true }, positionals: [] }
     ],
     [
       { argv: ['--foo=false'] },
-      { foo: true, _: [] }
+      { options: { foo: true }, positionals: [] }
     ],
     [
       { argv: ['--foo', 'true'] },
-      { foo: true, _: ['true'] }
+      { options: { foo: true }, positionals: ['true'] }
     ],
     [
-      { argv: ['--foo', 'true'], opts: { expectsValue: ['foo'] } },
-      { foo: 'true', _: [] }
+      { argv: ['--foo', 'true'], opts: { optionsWithValue: ['foo'] } },
+      { options: { foo: 'true' }, positionals: [] }
     ],
     [
-      { argv: ['--foo', 'false', 'false'], opts: { expectsValue: ['foo'] } },
-      { foo: 'false', _: ['false'] }
+      {
+        argv: ['--foo', 'false', 'false'],
+        opts: { optionsWithValue: ['foo'] }
+      },
+      { options: { foo: 'false' }, positionals: ['false'] }
     ],
     [
       { argv: ['--foo=true', '--foo=false'] },
-      { foo: 2, _: [] }
+      { options: { foo: true }, positionals: [] }
     ],
     [
       { argv: ['--foo', 'true', '--foo', 'false'] },
-      { foo: 2, _: ['true', 'false'] }
+      { options: { foo: true }, positionals: ['true', 'false'] }
     ],
     [
       { argv: ['--foo', 'true', '--foo', 'false'],
-        opts: { expectsValue: 'foo' } },
-      { foo: ['true', 'false'], _: [] }
+        opts: { optionsWithValue: 'foo', multiOptions: ['foo'] } },
+      { options: { foo: ['true', 'false'] }, positionals: [] }
+    ],
+    [
+      { argv: ['--foo', 'true', '--foo', 'false'],
+        opts: { optionsWithValue: 'foo' } },
+      { options: { foo: 'false' }, positionals: [] }
     ],
     [
       { argv: ['--foo', 'true', '--foo=false'],
-        opts: { expectsValue: 'foo' } },
-      { foo: ['true', 'false'], _: [] }
+        opts: { optionsWithValue: 'foo', multiOptions: ['foo'] } },
+      { options: { foo: ['true', 'false'] }, positionals: [] }
     ],
     [
       { argv: ['--foo', 'true', '--foo=false'] },
-      { foo: 2, _: ['true'] }
+      { options: { foo: true }, positionals: ['true'] }
     ],
     [
       {
         argv: ['--foo', 'bar', '--foo', 'baz'],
-        opts: { expectsValue: ['foo'] }
+        opts: { optionsWithValue: ['foo'], multiOptions: 'foo' }
       },
-      { foo: ['bar', 'baz'], _: [] }
+      { options: { foo: ['bar', 'baz'] }, positionals: [] }
     ],
     [
-      { argv: ['--foo', '--bar'], opts: { expectsValue: 'foo' } },
-      { foo: true, bar: true, _: [] }
+      { argv: ['--foo', '--bar'], opts: { optionsWithValue: 'foo' } },
+      { options: { foo: true, bar: true }, positionals: [] }
     ],
     [
-      { argv: ['--foo=--bar'], opts: { expectsValue: 'foo' } },
-      { foo: '--bar', _: [] }
+      { argv: ['--foo=--bar'], opts: { optionsWithValue: 'foo' } },
+      { options: { foo: '--bar' }, positionals: [] }
     ],
     [
       { argv: ['-_'] },
-      { _: [] }
+      { options: { _: true }, positionals: [] }
+    ],
+    [
+      { argv: ['--_=bar'], opts: { optionsWithValue: '_' } },
+      { options: { _: 'bar' }, positionals: [] }
     ],
     [
-      { argv: ['--_=bar'], opts: { expectsValue: '_' } },
-      { _: [] }
+      { argv: ['--_', 'bar'], opts: { optionsWithValue: '_' } },
+      { options: { _: 'bar' }, positionals: [] }
     ],
     [
-      { argv: ['--_', 'bar'], opts: { expectsValue: '_' } },
-      { _: [] }
+      { argv: [], opts: { optionsWithValue: 'foo', multiOptions: 'foo' } },
+      { options: { }, positionals: [] }
+    ],
+    [
+      { argv: [], opts: { multiOptions: 'foo' } },
+      { options: { }, positionals: [] }
     ]
   ]);
 
@@ -136,9 +163,13 @@ const { format, parseArgs } = require('util');
   const originalArgv = process.argv;
   process.argv = [process.execPath, __filename, '--foo', 'bar'];
   try {
-    assert.deepStrictEqual(parseArgs(), { foo: true, _: ['bar'] });
     assert.deepStrictEqual(
-      parseArgs({ expectsValue: 'foo' }), { foo: 'bar', _: [] }
+      parseArgs(),
+      { options: { foo: true }, positionals: ['bar'] }
+    );
+    assert.deepStrictEqual(
+      parseArgs({ optionsWithValue: 'foo' }),
+      { options: { foo: 'bar' }, positionals: [] }
     );
   } finally {
     process.argv = originalArgv;

From a0221e36e69e198180db06c4816212ce2fe3b71e Mon Sep 17 00:00:00 2001
From: Christopher Hiller <boneskull@boneskull.com>
Date: Thu, 10 Sep 2020 17:19:41 -0700
Subject: [PATCH 03/14] lint

---
 doc/api/util.md                 | 21 +++++++++++----------
 lib/internal/util/parse_args.js |  1 -
 2 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/doc/api/util.md b/doc/api/util.md
index d9f674abfd994d..d5ea7fda117572 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -962,7 +962,8 @@ added: REPLACEME
     strings which can be appear multiple times in `argv` and will be
     concatenated into an array
 * Returns: {Object} An object having properties:
-  * `options`, an Object with properties and values corresponding to parsed Options and Flags
+  * `options`, an Object with properties and values corresponding to parsed
+    Options and Flags
   * `positionals`, an Array containing containing Positionals
 
 The `util.parseArgs` function parses command-line arguments from an array of
@@ -1020,8 +1021,9 @@ Arguments fall into one of three catgories:
   * When appearing _once_ in the array, the value of the property will be `true`
   * When _repeated_ in the array, the value of the property becomes a count of
     repetitions (e.g., `['-v', '-v' '-v']` results in `{ v: 3 }`)
-* _Options_, declared by `optionsWithValue`, which begin with one or more dashes,
-  and _do_ have an associated value (e.g., `node app.js --require script.js`)
+* _Options_, declared by `optionsWithValue`, which begin with one or more
+  dashes, and _do_ have an associated value (e.g., `node app.js --require
+  script.js`)
   * Use the `optionsWithValue` option to `util.parseArgs` to declare Options
   * The Option _name_ is the string following the prefix of one-or-more dashes,
     e.g., the name of `--foo` is `foo`
@@ -1036,11 +1038,10 @@ Arguments fall into one of three catgories:
     * The array ends with the Option name (e.g., `['--foo']`)
   * When repeated, values are concatenated into an Array; unlike Flags, they _do
     not_ become a numeric count
-  * When an Option name appears in the Array (or string) of `optionsWithValue`, and
-    does _not_ appear in the `argv` array, the resulting object _will not_
-    contain a property with this Option name (e.g.,
-    `util.parseArgs(['--bar'], { optionsWithValue: 'foo' })` will result in
-    `{bar: true, _: [] }`
+  * When an Option name appears in the Array (or string) of `optionsWithValue`,
+    and does _not_ appear in the `argv` array, the resulting object _will not_
+    contain a property with this Option name (e.g., `util.parseArgs(['--bar'],
+    { optionsWithValue: 'foo' })` will result in `{bar: true, _: [] }`
 * _Positionals_ (or "positional arguments"), which _do not_ begin with one or
   more dashes (e.g., `['script.js']`), _or_ every item in the `argv` Array
   following a `--` (e.g., `['--', 'script.js']`)
@@ -1051,8 +1052,8 @@ Arguments fall into one of three catgories:
   * Positionals will _always_ be parsed verbatim (e.g., `['--', '--foo']` will
     result in an object of `{_: ['--foo']}`)
 
-A Flag or Option with having the name `_` will be ignored. If it was declared
-as an Option (via the `optionsWithValue` option), its value will be ignored as well.
+A Flag or Option having the name `_` will be ignored. If it was declared as an
+Option (via the `optionsWithValue` option), its value will be ignored as well.
 
 `util.parseArgs` does not consider "short" arguments (e.g., `-v`) to be
 different than "long" arguments (e.g., `--verbose`).  Furthermore, it does not
diff --git a/lib/internal/util/parse_args.js b/lib/internal/util/parse_args.js
index 3bd6cdfd15ce99..75aef2032a5a5b 100644
--- a/lib/internal/util/parse_args.js
+++ b/lib/internal/util/parse_args.js
@@ -4,7 +4,6 @@ const {
   ArrayIsArray,
   ArrayPrototypePush,
   ArrayPrototypeSlice,
-  Number,
   SafeSet,
   StringPrototypeReplace,
   StringPrototypeSplit,

From 971039cf0870b68a5ac6ecd006fa11cb5b28cb0f Mon Sep 17 00:00:00 2001
From: Christopher Hiller <boneskull@boneskull.com>
Date: Fri, 11 Sep 2020 10:58:41 -0700
Subject: [PATCH 04/14] update docstring

---
 lib/internal/util/parse_args.js | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/lib/internal/util/parse_args.js b/lib/internal/util/parse_args.js
index 75aef2032a5a5b..9823eeabd07bec 100644
--- a/lib/internal/util/parse_args.js
+++ b/lib/internal/util/parse_args.js
@@ -15,27 +15,26 @@ const { ERR_INVALID_ARG_TYPE } = require('internal/errors').codes;
  * Returns an Object representation of command-line arguments.
  *
  * Default behavior:
- * - All arguments are considered "boolean flags"; in the returned
- *   object, the key is the argument (if present), and the value will be `true`.
+ * - All arguments are considered "boolean flags"; in the `options` property of
+ *   returned object, the key is the argument (if present), and the value will
+ *   be `true`.
  * - Uses `process.argv.slice(2)`, but can accept an explicit array of strings.
  * - Argument(s) specified in `opts.optionsWithValue` will have `string` values
  *   instead of `true`; the subsequent item in the `argv` array will be consumed
- *   if a `=` is not used.
- * - If `=` is present, the value will be boolean if and only if the RHS of the
- *   string is one of string `true` or `false`
+ *   if a `=` is not used
  * - "Bare" arguments are those which do not begin with a `-` or `--` and those
- *   after a bare `--`; these will be returned as items of the `_` array
+ *   after a bare `--`; these will be returned as items of the `positionals`
+ *   array
  * - The `positionals` array will always be present, even if empty.
  * - The `options` Object will always be present, even if empty.
- * - Repeated arguments are combined into an array
  * @param {string[]} [argv=process.argv.slice(2)] - Array of script arguments as
  * strings
  * @param {Object} [options] - Options
  * @param {string[]|string} [opts.optionsWithValue] - This argument (or
  * arguments) expect a value
  * @param {string[]|string} [opts.multiOptions] - This argument (or arguments)
- * can be specified multiple times and its values will be concatenated into
- * an array
+ * can be specified multiple times and its values will be concatenated into an
+ * array
  * @example
  * parseArgs(['--foo', '--bar'])
  *   // {options: { foo: true, bar: true }, positionals: []}

From 84b34cc821812257dc74f5d053983f012919d857 Mon Sep 17 00:00:00 2001
From: Christopher Hiller <boneskull@boneskull.com>
Date: Fri, 11 Sep 2020 10:59:54 -0700
Subject: [PATCH 05/14] update docstring more

---
 lib/internal/util/parse_args.js | 1 +
 1 file changed, 1 insertion(+)

diff --git a/lib/internal/util/parse_args.js b/lib/internal/util/parse_args.js
index 9823eeabd07bec..787b5ab8aac6c1 100644
--- a/lib/internal/util/parse_args.js
+++ b/lib/internal/util/parse_args.js
@@ -35,6 +35,7 @@ const { ERR_INVALID_ARG_TYPE } = require('internal/errors').codes;
  * @param {string[]|string} [opts.multiOptions] - This argument (or arguments)
  * can be specified multiple times and its values will be concatenated into an
  * array
+ * @returns {{options: Object, positionals: string[]}} Parsed arguments
  * @example
  * parseArgs(['--foo', '--bar'])
  *   // {options: { foo: true, bar: true }, positionals: []}

From 003407960cbeb6bcd54423fc248787c2130bd1c5 Mon Sep 17 00:00:00 2001
From: Christopher Hiller <boneskull@boneskull.com>
Date: Fri, 11 Sep 2020 11:03:29 -0700
Subject: [PATCH 06/14] update camel case related text

---
 doc/api/util.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/doc/api/util.md b/doc/api/util.md
index d5ea7fda117572..f0d254af0102f5 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -1060,8 +1060,9 @@ different than "long" arguments (e.g., `--verbose`).  Furthermore, it does not
 allow concatenation of short arguments (e.g., `-v -D` cannot be expressed as
 `-vD`).
 
-Conversion to/from "camelCase" occurs; a Flag or Option name of `no-color`
-results in an object with a `no-color` property.
+_No_ conversion to/from "camelCase" occurs; a Flag or Option name of `no-color`
+results in an object with a `no-color` property.  A Flag or Option name of
+`noColor` results in an object with a `noColor` property.
 
 ## `util.promisify(original)`
 <!-- YAML

From d3492082b7e45e2061e0a49a829ff55a02b31046 Mon Sep 17 00:00:00 2001
From: Christopher Hiller <boneskull@boneskull.com>
Date: Fri, 11 Sep 2020 11:55:22 -0700
Subject: [PATCH 07/14] doc updates

---
 doc/api/util.md | 164 +++++++++++++++++++++++++++++-------------------
 1 file changed, 100 insertions(+), 64 deletions(-)

diff --git a/doc/api/util.md b/doc/api/util.md
index f0d254af0102f5..7346680d7abf97 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -951,22 +951,23 @@ equality.
 added: REPLACEME
 -->
 
-* `argv` {Array<string>|Object} (Optional) Array of argument strings; defaults
+* `argv` {string[]|Object} (Optional) Array of argument strings; defaults
   to [`process.argv.slice(2)`](process_argv). If an Object, the default is used,
   and this parameter is considered to be the `options` parameter.
 * `options` {Object} (Optional) The `options` parameter, if present, is an
-  object supporting the following property:
-  * `optionsWithValue` {Array<string>|string} (Optional) One or more argument
-    strings which _expect a value_ when present
-  * `multiOptions` {Array<string>|string} (Optional) One or more argument
-    strings which can be appear multiple times in `argv` and will be
-    concatenated into an array
+  object supporting the following properties:
+  * `optionsWithValue` {string[]|string} (Optional) One or more argument
+    strings which _expect a value_ when present (see [Options][]
+    for details)
+  * `multiOptions` {string[]|string} (Optional) One or more argument
+    strings which, when appearing multiple times in `argv`, will be concatenated
+    into an Array
 * Returns: {Object} An object having properties:
-  * `options`, an Object with properties and values corresponding to parsed
-    Options and Flags
-  * `positionals`, an Array containing containing Positionals
+  * `options` {Object}, having properties and values corresponding to parsed
+    [Options][] and [Flags][], if any
+  * `positionals` {string[]}, containing [Positionals][], if any
 
-The `util.parseArgs` function parses command-line arguments from an array of
+The `util.parseArgs` function parses command-line arguments from an Array of
 strings and returns an object representation.
 
 Example using [`process.argv`][]:
@@ -976,8 +977,7 @@ Example using [`process.argv`][]:
 // called via `node script.js --foo bar baz`
 const argv = util.parseArgs();
 
-// argv.foo === true
-if (argv.foo) {
+if (argv.foo === true) {
   console.log(argv.positionals); // prints [ 'bar', 'baz' ]
 }
 ```
@@ -1007,62 +1007,95 @@ const argv = util.parseArgs(
 console.log(argv.options.bar); // prints [ 'bar', 'baz' ]
 ```
 
+Example with custom `argv` and `multiOptions`:
+
+```js
+const argv = util.parseArgs(
+  ['-v', '-v', '-v'],
+  { multiOptions: 'v' }
+);
+
+console.log(argv.options.v); // prints [ true, true, true ]
+```
+
 [`ERR_INVALID_ARG_TYPE`][] will be thrown if the `argv` parameter is not an
 Array.
 
 Arguments fall into one of three catgories:
 
-* _Flags_, which begin with one or more dashes (`-`), and _do not_ have an
-  associated string value (e.g., `node app.js --verbose`)
-  * These will be parsed automatically; you do not need to "declare" them
-  * The Flag _name_ is the string following the prefix of one-or-more dashes,
-    e.g., the name of `--foo` is `foo`
-  * Flag names become property names in the returned object
-  * When appearing _once_ in the array, the value of the property will be `true`
-  * When _repeated_ in the array, the value of the property becomes a count of
-    repetitions (e.g., `['-v', '-v' '-v']` results in `{ v: 3 }`)
-* _Options_, declared by `optionsWithValue`, which begin with one or more
-  dashes, and _do_ have an associated value (e.g., `node app.js --require
-  script.js`)
-  * Use the `optionsWithValue` option to `util.parseArgs` to declare Options
-  * The Option _name_ is the string following the prefix of one-or-more dashes,
-    e.g., the name of `--foo` is `foo`
-  * The Option _value_ is the next string following the name, e.g., the Option
-    value of `['--foo' 'bar']` is `bar`
-  * Option values may be provided _with or without_ a `=` separator (e.g.,
-    `['--require=script.js']` is equivalent to `['--require', 'script.js']`)
-  * An Option value is considered "missing" and is results in `true` when:
-    * A `=` does not separate the Option name from its value (e.g., `--foo bar`)
-      _and_ the following argument begins with a dash (e.g., `['--foo',
-      '--bar']`), _OR_
-    * The array ends with the Option name (e.g., `['--foo']`)
-  * When repeated, values are concatenated into an Array; unlike Flags, they _do
-    not_ become a numeric count
-  * When an Option name appears in the Array (or string) of `optionsWithValue`,
-    and does _not_ appear in the `argv` array, the resulting object _will not_
-    contain a property with this Option name (e.g., `util.parseArgs(['--bar'],
-    { optionsWithValue: 'foo' })` will result in `{bar: true, _: [] }`
-* _Positionals_ (or "positional arguments"), which _do not_ begin with one or
-  more dashes (e.g., `['script.js']`), _or_ every item in the `argv` Array
-  following a `--` (e.g., `['--', 'script.js']`)
-  * Positionals appear in the Array property `_` of the returned object
-  * The `_` property will _always_ be present and an Array, even if empty
-  * If present in the `argv` Array, `--` is discarded and is omitted from the
-    returned object
-  * Positionals will _always_ be parsed verbatim (e.g., `['--', '--foo']` will
-    result in an object of `{_: ['--foo']}`)
-
-A Flag or Option having the name `_` will be ignored. If it was declared as an
-Option (via the `optionsWithValue` option), its value will be ignored as well.
-
-`util.parseArgs` does not consider "short" arguments (e.g., `-v`) to be
-different than "long" arguments (e.g., `--verbose`).  Furthermore, it does not
-allow concatenation of short arguments (e.g., `-v -D` cannot be expressed as
-`-vD`).
-
-_No_ conversion to/from "camelCase" occurs; a Flag or Option name of `no-color`
-results in an object with a `no-color` property.  A Flag or Option name of
-`noColor` results in an object with a `noColor` property.
+### Flags
+
+_Flags_ are arguments which begin with one or more dashes (`-`), and _do not_
+have an associated string value (e.g., `node app.js --verbose`).
+
+* These will be parsed automatically; you do not need to "declare" them
+* The Flag _name_ is the string following the prefix of _one or more_ dashes,
+  e.g., the name of `--foo` is `foo`
+* Flag names become property names in the `options` property of the returned
+  object
+* By default, when appearing any number of times in the `argv` Array, the value
+  of the property will be `true`. To get a "count" of the times a Flag is
+  repeated, specify the Flag name in the `multiOptions` option; this will parsed
+  to an Array of `true` values, and you can derive the "count" from the `length`
+  property of this Array
+* When a Flag appears in `multiOptions`, and when provided in `argv`, the value
+  in the returned object will _always_ be an Array (even if it is only provided
+  once)
+* A Flag appearing in `multiOptions` but not in the `argv` Array will be omitted
+  from the `options` property of the returned object
+
+### Options
+
+_Options_ are arguments which begin with one or more dashes (`-`), and _do_ have
+an associated value (e.g., `node app.js --require script.js`).
+
+* Use the `optionsWithValue` option to `util.parseArgs` to declare Options
+* The Option _name_ is the string following the prefix of one-or-more dashes,
+  e.g., the name of `--foo` is `foo`
+* The Option _value_ is the next string following the name, e.g., the Option
+  value of `['--foo' 'bar']` is `bar`
+* Option values may be provided _with or without_ a `=` separator (e.g.,
+  `['--require=script.js']` is equivalent to `['--require', 'script.js']`)
+* If an Option value is not provided, the Option will be omitted from the
+  `options` property of the returned object
+* An argument-like value (a value beginning with one or more dashes) immediately
+  following an Option in the `argv` Array will cause the Option to be omitted
+  from the `options` property of the returned object _unless_ the `=` separator
+  is used; e.g., `['--foo', '--bar']` where `foo` is an Option will return
+  `{options: {bar: true}, positionals: []}`, but `['--foo=--bar']` will return
+  `{options: {foo: '--bar'}, positionals: []}`
+* When an Option name appears in the Array (or string) of `optionsWithValue`,
+  and does _not_ appear in the `argv` Array, the resulting object _will not_
+  contain a property with this Option name (e.g., `util.parseArgs(['--bar'], {
+  optionsWithValue: 'foo' })` will result in `{options: {bar: true},
+  positionals: [] }`
+* When an Option appears in `multiOptions`, and when provided in `argv`, the
+  value in the returned object will _always_ be an Array (even if it is only
+  provided once)
+
+### Positionals
+
+_Positionals_ (or "positional arguments") are arguments which _do not_ begin
+with one or more dashes (e.g., `['script.js']`), _and/or_ all items in the
+`argv` Array following a `--` (e.g., `['--', 'script.js']`).
+
+* Positionals appear in the Array property `positionals` of the returned object
+* The `positionals` property will _always_ be present and an Array, even if
+  empty
+* If present in the `argv` Array, `--` is discarded and is omitted from the
+  returned object
+* Positionals will _always_ be parsed verbatim (e.g., `['--', '--foo']` will
+  result in an object of `{positionals: ['--foo'], options: {}}`)
+
+Please note:
+
+* `util.parseArgs` does not consider "short" arguments (e.g., `-v`) to be
+  different than "long" arguments (e.g., `--verbose`).  Furthermore, it does not
+  allow concatenation of short arguments (e.g., `-v -D` cannot be expressed as
+  `-vD`).
+* _No_ conversion to or from "camelCase" occurs; a Flag or Option name of
+  `no-color` results in an object with a `no-color` property. A Flag or Option
+  name of `noColor` results in an object with a `noColor` property.
 
 ## `util.promisify(original)`
 <!-- YAML
@@ -2616,9 +2649,12 @@ util.log('Timestamped message.');
 [constructor]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/constructor
 [default sort]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort
 [`ERR_INVALID_ARG_TYPE`]: errors.html#ERR_INVALID_ARG_TYPE
+[Flags]: #util_flags
 [global symbol registry]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/for
 [list of deprecated APIS]: deprecations.html#deprecations_list_of_deprecated_apis
 [`napi_create_external()`]: n-api.html#n_api_napi_create_external
+[Options]: #util_options
+[Positionals]: #util_positionals
 [`process.argv`]: process.html#process_process_argv
 [semantically incompatible]: https://github.com/nodejs/node/issues/4179
 [util.inspect.custom]: #util_util_inspect_custom

From 1d5cd77b9689c27b39f902b0b9ca46df6af5ff6e Mon Sep 17 00:00:00 2001
From: Christopher Hiller <boneskull@boneskull.com>
Date: Fri, 11 Sep 2020 12:00:19 -0700
Subject: [PATCH 08/14] doc formatting tweaks

---
 doc/api/util.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/doc/api/util.md b/doc/api/util.md
index 7346680d7abf97..68c2b1f59b8a02 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -946,7 +946,7 @@ Otherwise, returns `false`.
 See [`assert.deepStrictEqual()`][] for more information about deep strict
 equality.
 
-## `util.parseArgs([argv[, options]])`
+## `util.parseArgs([argv][, options])`
 <!-- YAML
 added: REPLACEME
 -->
@@ -954,18 +954,18 @@ added: REPLACEME
 * `argv` {string[]|Object} (Optional) Array of argument strings; defaults
   to [`process.argv.slice(2)`](process_argv). If an Object, the default is used,
   and this parameter is considered to be the `options` parameter.
-* `options` {Object} (Optional) The `options` parameter, if present, is an
+* `options` {Object} (Optional) The `options` parameter is an
   object supporting the following properties:
   * `optionsWithValue` {string[]|string} (Optional) One or more argument
-    strings which _expect a value_ when present (see [Options][]
+    strings which _expect a value_ when present in `argv` (see [Options][]
     for details)
   * `multiOptions` {string[]|string} (Optional) One or more argument
     strings which, when appearing multiple times in `argv`, will be concatenated
     into an Array
 * Returns: {Object} An object having properties:
   * `options` {Object}, having properties and values corresponding to parsed
-    [Options][] and [Flags][], if any
-  * `positionals` {string[]}, containing [Positionals][], if any
+    [Options][] and [Flags][]
+  * `positionals` {string[]}, containing [Positionals][]
 
 The `util.parseArgs` function parses command-line arguments from an Array of
 strings and returns an object representation.

From d64e82aac326feb6288a25aa3d8799c8bf1daa2a Mon Sep 17 00:00:00 2001
From: Christopher Hiller <boneskull@boneskull.com>
Date: Fri, 11 Sep 2020 12:05:33 -0700
Subject: [PATCH 09/14] docstring tweaks

---
 lib/internal/util/parse_args.js | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/lib/internal/util/parse_args.js b/lib/internal/util/parse_args.js
index 787b5ab8aac6c1..df687bfedb2166 100644
--- a/lib/internal/util/parse_args.js
+++ b/lib/internal/util/parse_args.js
@@ -22,9 +22,9 @@ const { ERR_INVALID_ARG_TYPE } = require('internal/errors').codes;
  * - Argument(s) specified in `opts.optionsWithValue` will have `string` values
  *   instead of `true`; the subsequent item in the `argv` array will be consumed
  *   if a `=` is not used
- * - "Bare" arguments are those which do not begin with a `-` or `--` and those
- *   after a bare `--`; these will be returned as items of the `positionals`
- *   array
+ * - "Bare" arguments (positionals) are those which do not begin with a `-` or
+ *   `--` and those after a bare `--`; these will be returned as items of the
+ *   `positionals` array
  * - The `positionals` array will always be present, even if empty.
  * - The `options` Object will always be present, even if empty.
  * @param {string[]} [argv=process.argv.slice(2)] - Array of script arguments as
@@ -64,6 +64,8 @@ const { ERR_INVALID_ARG_TYPE } = require('internal/errors').codes;
  *   // {options: {foo: true}, positionals: []}
  * parseArgs(['--foo', '--foo'], {multiOptions: ['foo']})
  *   // {options: {foo: [true, true]}, positionals: []}
+ * parseArgs(['--very-wordy-option'])
+ *   // {options: {'very-wordy-option': true}, positionals: []}
  */
 const parseArgs = (
   argv = ArrayPrototypeSlice(process.argv, 2),

From 4dbdca31b8056b40949cbc0cb6db91182454515e Mon Sep 17 00:00:00 2001
From: Christopher Hiller <boneskull@boneskull.com>
Date: Fri, 11 Sep 2020 12:10:45 -0700
Subject: [PATCH 10/14] add note about Flags dropping string values

---
 doc/api/util.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/doc/api/util.md b/doc/api/util.md
index 68c2b1f59b8a02..2db13c4117c92a 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -1043,6 +1043,10 @@ have an associated string value (e.g., `node app.js --verbose`).
   once)
 * A Flag appearing in `multiOptions` but not in the `argv` Array will be omitted
   from the `options` property of the returned object
+* If a string value is erroneously provided in `argv` for a Flag via the `=`
+  separator, the string value will be replaced with `true`; e.g.,
+  `['--require=script.js']` becomes `{options: {require: true}}, positionals:
+  []}`
 
 ### Options
 

From 97f7e88a68cd487ac9b95c811ceec7c0dd8cb0a2 Mon Sep 17 00:00:00 2001
From: Christopher Hiller <boneskull@boneskull.com>
Date: Mon, 14 Sep 2020 14:48:13 -0700
Subject: [PATCH 11/14] review updates

---
 doc/api/util.md                      | 10 +++++-----
 lib/internal/util/parse_args.js      | 21 ++++++++++-----------
 test/parallel/test-util-parseargs.js |  4 ++++
 3 files changed, 19 insertions(+), 16 deletions(-)

diff --git a/doc/api/util.md b/doc/api/util.md
index 2db13c4117c92a..065eb80f45d27e 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -1035,9 +1035,9 @@ have an associated string value (e.g., `node app.js --verbose`).
   object
 * By default, when appearing any number of times in the `argv` Array, the value
   of the property will be `true`. To get a "count" of the times a Flag is
-  repeated, specify the Flag name in the `multiOptions` option; this will parsed
-  to an Array of `true` values, and you can derive the "count" from the `length`
-  property of this Array
+  repeated, specify the Flag name in the `multiOptions` option; this will be
+  parsed to an Array of `true` values, and you can derive the "count" from the
+  `length` property of this Array
 * When a Flag appears in `multiOptions`, and when provided in `argv`, the value
   in the returned object will _always_ be an Array (even if it is only provided
   once)
@@ -1050,7 +1050,7 @@ have an associated string value (e.g., `node app.js --verbose`).
 
 ### Options
 
-_Options_ are arguments which begin with one or more dashes (`-`), and _do_ have
+_Options_ are arguments which begin with one or more dashes (`-`), and _expect_
 an associated value (e.g., `node app.js --require script.js`).
 
 * Use the `optionsWithValue` option to `util.parseArgs` to declare Options
@@ -1091,7 +1091,7 @@ with one or more dashes (e.g., `['script.js']`), _and/or_ all items in the
 * Positionals will _always_ be parsed verbatim (e.g., `['--', '--foo']` will
   result in an object of `{positionals: ['--foo'], options: {}}`)
 
-Please note:
+### Additional Considerations
 
 * `util.parseArgs` does not consider "short" arguments (e.g., `-v`) to be
   different than "long" arguments (e.g., `--verbose`).  Furthermore, it does not
diff --git a/lib/internal/util/parse_args.js b/lib/internal/util/parse_args.js
index df687bfedb2166..76ee5799e498d9 100644
--- a/lib/internal/util/parse_args.js
+++ b/lib/internal/util/parse_args.js
@@ -30,11 +30,11 @@ const { ERR_INVALID_ARG_TYPE } = require('internal/errors').codes;
  * @param {string[]} [argv=process.argv.slice(2)] - Array of script arguments as
  * strings
  * @param {Object} [options] - Options
- * @param {string[]|string} [opts.optionsWithValue] - This argument (or
+ * @param {string[]|string} [options.optionsWithValue] - This argument (or
  * arguments) expect a value
- * @param {string[]|string} [opts.multiOptions] - This argument (or arguments)
- * can be specified multiple times and its values will be concatenated into an
- * array
+ * @param {string[]|string} [options.multiOptions] - This argument (or
+ * arguments) can be specified multiple times and its values will be
+ * concatenated into an array
  * @returns {{options: Object, positionals: string[]}} Parsed arguments
  * @example
  * parseArgs(['--foo', '--bar'])
@@ -92,11 +92,8 @@ const parseArgs = (
   const result = { positionals: [], options: {} };
 
   let pos = 0;
-  while (true) {
+  while (pos < argv.length) {
     const arg = argv[pos];
-    if (arg === undefined) {
-      return result;
-    }
     if (StringPrototypeStartsWith(arg, '-')) {
       // Everything after a bare '--' is considered a positional argument
       // and is returned verbatim
@@ -115,8 +112,9 @@ const parseArgs = (
       // and the next item is not itself a flag or option
       if (optionsWithValue.has(optionName)) {
         if (optionValue === undefined) {
-          optionValue = StringPrototypeStartsWith(argv[pos + 1], '-') ||
-              argv[++pos];
+          optionValue = (
+            argv[pos + 1] && StringPrototypeStartsWith(argv[pos + 1], '-')
+          ) || argv[++pos];
         }
       } else {
         optionValue = true;
@@ -130,7 +128,7 @@ const parseArgs = (
         } else {
           ArrayPrototypePush(result.options[optionName], optionValue);
         }
-      } else {
+      } else if (optionValue !== undefined) {
         result.options[optionName] = optionValue;
       }
     } else {
@@ -138,6 +136,7 @@ const parseArgs = (
     }
     pos++;
   }
+  return result;
 };
 
 module.exports = {
diff --git a/test/parallel/test-util-parseargs.js b/test/parallel/test-util-parseargs.js
index c516f0b280b9a4..186272e006fe81 100644
--- a/test/parallel/test-util-parseargs.js
+++ b/test/parallel/test-util-parseargs.js
@@ -145,6 +145,10 @@ const { format, parseArgs } = require('util');
     [
       { argv: [], opts: { multiOptions: 'foo' } },
       { options: { }, positionals: [] }
+    ],
+    [
+      { argv: ['--foo'], opts: { optionsWithValue: 'foo' } },
+      { options: {}, positionals: [] }
     ]
   ]);
 

From b2be252ded01ebaf9723c3af923f36a514296f55 Mon Sep 17 00:00:00 2001
From: Christopher Hiller <boneskull@boneskull.com>
Date: Wed, 16 Sep 2020 15:32:05 -0700
Subject: [PATCH 12/14] add special-case for value of "false" for Flags

---
 doc/api/util.md                      | 10 ++++++----
 lib/internal/util/parse_args.js      |  7 ++++++-
 test/parallel/test-util-parseargs.js | 12 ++++++++++--
 3 files changed, 22 insertions(+), 7 deletions(-)

diff --git a/doc/api/util.md b/doc/api/util.md
index 065eb80f45d27e..7a4709e88a93c1 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -1043,10 +1043,12 @@ have an associated string value (e.g., `node app.js --verbose`).
   once)
 * A Flag appearing in `multiOptions` but not in the `argv` Array will be omitted
   from the `options` property of the returned object
-* If a string value is erroneously provided in `argv` for a Flag via the `=`
-  separator, the string value will be replaced with `true`; e.g.,
-  `['--require=script.js']` becomes `{options: {require: true}}, positionals:
-  []}`
+* _Special case for negated Flags_: If a string value of `false` is provided in
+  `argv` for a Flag via the `=` separator, the value will become boolean
+  `false`, e.g., `['--verbose=false']` becomes `{options: {verbose: false}},
+  positionals: []}`; any value other than the string `false` will become `true`,
+  and if `=` is not provided, the value is interpreted as a
+  [Positional][Positionals]
 
 ### Options
 
diff --git a/lib/internal/util/parse_args.js b/lib/internal/util/parse_args.js
index 76ee5799e498d9..9ccc0e470cb2c1 100644
--- a/lib/internal/util/parse_args.js
+++ b/lib/internal/util/parse_args.js
@@ -66,6 +66,10 @@ const { ERR_INVALID_ARG_TYPE } = require('internal/errors').codes;
  *   // {options: {foo: [true, true]}, positionals: []}
  * parseArgs(['--very-wordy-option'])
  *   // {options: {'very-wordy-option': true}, positionals: []}
+ * parseArgs(['--verbose=false'])
+ *   // {options: {verbose: false}, positionals: []}
+ * parseArgs(['--verbose', 'false'])
+ *   // {options: {verbose: true}, positionals: ['false']}
  */
 const parseArgs = (
   argv = ArrayPrototypeSlice(process.argv, 2),
@@ -117,7 +121,8 @@ const parseArgs = (
           ) || argv[++pos];
         }
       } else {
-        optionValue = true;
+        // To get a `false` value for a Flag, use e.g., ['--flag=false']
+        optionValue = optionValue !== 'false';
       }
 
       if (multiOptions.has(optionName)) {
diff --git a/test/parallel/test-util-parseargs.js b/test/parallel/test-util-parseargs.js
index 186272e006fe81..b4f5c335536bc9 100644
--- a/test/parallel/test-util-parseargs.js
+++ b/test/parallel/test-util-parseargs.js
@@ -67,12 +67,20 @@ const { format, parseArgs } = require('util');
     ],
     [
       { argv: ['--foo=false'] },
+      { options: { foo: false }, positionals: [] }
+    ],
+    [
+      { argv: ['--foo=bar'] },
       { options: { foo: true }, positionals: [] }
     ],
     [
       { argv: ['--foo', 'true'] },
       { options: { foo: true }, positionals: ['true'] }
     ],
+    [
+      { argv: ['--foo', 'false'] },
+      { options: { foo: true }, positionals: ['false'] }
+    ],
     [
       { argv: ['--foo', 'true'], opts: { optionsWithValue: ['foo'] } },
       { options: { foo: 'true' }, positionals: [] }
@@ -86,7 +94,7 @@ const { format, parseArgs } = require('util');
     ],
     [
       { argv: ['--foo=true', '--foo=false'] },
-      { options: { foo: true }, positionals: [] }
+      { options: { foo: false }, positionals: [] }
     ],
     [
       { argv: ['--foo', 'true', '--foo', 'false'] },
@@ -109,7 +117,7 @@ const { format, parseArgs } = require('util');
     ],
     [
       { argv: ['--foo', 'true', '--foo=false'] },
-      { options: { foo: true }, positionals: ['true'] }
+      { options: { foo: false }, positionals: ['true'] }
     ],
     [
       {

From 694f9c624534ddf0e32db73476964da314baa238 Mon Sep 17 00:00:00 2001
From: Christopher Hiller <boneskull@boneskull.com>
Date: Wed, 16 Sep 2020 15:37:09 -0700
Subject: [PATCH 13/14] missing values for Options become an empty string

---
 doc/api/util.md                      | 4 ++--
 lib/internal/util/parse_args.js      | 2 +-
 test/parallel/test-util-parseargs.js | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/doc/api/util.md b/doc/api/util.md
index 7a4709e88a93c1..4460a9219b2a69 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -1062,8 +1062,8 @@ an associated value (e.g., `node app.js --require script.js`).
   value of `['--foo' 'bar']` is `bar`
 * Option values may be provided _with or without_ a `=` separator (e.g.,
   `['--require=script.js']` is equivalent to `['--require', 'script.js']`)
-* If an Option value is not provided, the Option will be omitted from the
-  `options` property of the returned object
+* If an Option value is not found in `argv`, the associated value will be parsed
+  to an empty string (`''`)
 * An argument-like value (a value beginning with one or more dashes) immediately
   following an Option in the `argv` Array will cause the Option to be omitted
   from the `options` property of the returned object _unless_ the `=` separator
diff --git a/lib/internal/util/parse_args.js b/lib/internal/util/parse_args.js
index 9ccc0e470cb2c1..d1624dd36cdf65 100644
--- a/lib/internal/util/parse_args.js
+++ b/lib/internal/util/parse_args.js
@@ -118,7 +118,7 @@ const parseArgs = (
         if (optionValue === undefined) {
           optionValue = (
             argv[pos + 1] && StringPrototypeStartsWith(argv[pos + 1], '-')
-          ) || argv[++pos];
+          ) || argv[++pos] || '';
         }
       } else {
         // To get a `false` value for a Flag, use e.g., ['--flag=false']
diff --git a/test/parallel/test-util-parseargs.js b/test/parallel/test-util-parseargs.js
index b4f5c335536bc9..8edcb559174bcb 100644
--- a/test/parallel/test-util-parseargs.js
+++ b/test/parallel/test-util-parseargs.js
@@ -156,7 +156,7 @@ const { format, parseArgs } = require('util');
     ],
     [
       { argv: ['--foo'], opts: { optionsWithValue: 'foo' } },
-      { options: {}, positionals: [] }
+      { options: { foo: '' }, positionals: [] }
     ]
   ]);
 

From 3a7f3b1bbf913e9e3117a8523d6ba00aca042bff Mon Sep 17 00:00:00 2001
From: Christopher Hiller <boneskull@boneskull.com>
Date: Thu, 17 Sep 2020 11:31:32 -0700
Subject: [PATCH 14/14] update signature in util.md

---
 doc/api/util.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/api/util.md b/doc/api/util.md
index 4460a9219b2a69..37b7b9e1053874 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -951,7 +951,7 @@ equality.
 added: REPLACEME
 -->
 
-* `argv` {string[]|Object} (Optional) Array of argument strings; defaults
+* `argv` {string[]} (Optional) Array of argument strings; defaults
   to [`process.argv.slice(2)`](process_argv). If an Object, the default is used,
   and this parameter is considered to be the `options` parameter.
 * `options` {Object} (Optional) The `options` parameter is an