feat: add parsed meta-data to returned properties

README.md

@@ -89,12 +89,13 @@ console.log(values, positionals);
 ```
 
 Detailed parse information is available for adding custom behaviours by
-specifying `tokens: true` in the configuration. The returned tokens have
+specifying `tokens: true` in the configuration.
+The returned tokens have
 properties describing:
 
 * all tokens
   * `kind` { string } One of 'option', 'positional', or 'option-terminator'.
-  * `index` { number } Index of element in `args` containing token.
+  * `index` { number } Index of element in `args` containing token. So the source argument for a token is `args[token.index]`.
 * option tokens
   * `name` { string } Long name of option.
   * `rawName` { string } How option used in args, like `-f` of `--foo`.
@@ -103,65 +104,94 @@ Undefined for boolean options.
   * `inlineValue` { boolean | undefined } Whether option value specified inline,
 like `--foo=bar`.
 * positional tokens
-  * `value` { string } the value of the positional argument in args (i.e. `args[index]`).
+  * `value` { string } The value of the positional argument in args (i.e. `args[index]`).
 * option-terminator token
 
-For example, assuming the following script which uses
-automatic detection of options and no error checking:
+The returned tokens are in the order encountered in the input args. Options that appear
+more than once in args produce a token for each use.
+Short option groups like `-xy` expand to a token for each option. So `-xxx` produces
+three tokens.
+
+For example to use the returned tokens to add support for a negated option like `--no-color`, the tokens
+can be reprocessed to change the value stored for the negated option.
 
 ```mjs
 import { parseArgs } from 'node:util';
-console.log(parseArgs({ strict: false, tokens: true }));
+
+const options = {
+  ['color']: { type: 'boolean' },
+  ['no-color']: { type: 'boolean' },
+  ['logfile']: { type: 'string' },
+  ['no-logfile']: { type: 'boolean' },
+};
+const { values, tokens } = parseArgs({ options, tokens: true });
+
+// Reprocess the option tokens and overwrite the returned values.
+tokens
+  .filter((token) => token.kind === 'option')
+  .forEach((token) => {
+    if (token.name.startsWith('no-')) {
+      // Store foo:false for --no-foo
+      const positiveName = token.name.slice(3);
+      values[positiveName] = false;
+      delete values[token.name];
+    } else {
+      // Resave value so last one wins if both --foo and --no-foo.
+      values[token.name] = token.value ?? true;
+    }
+  });
+
+const color = values.color;
+const logfile = values.logfile ?? 'default.log';
+
+console.log({ logfile, color });
 ```
 
 ```cjs
 const { parseArgs } = require('node:util');
-console.log(parseArgs({ strict: false, tokens: true }));
+
+const options = {
+  ['color']: { type: 'boolean' },
+  ['no-color']: { type: 'boolean' },
+  ['logfile']: { type: 'string' },
+  ['no-logfile']: { type: 'boolean' },
+};
+const { values, tokens } = parseArgs({ options, tokens: true });
+
+// Reprocess the option tokens and overwrite the returned values.
+tokens
+  .filter((token) => token.kind === 'option')
+  .forEach((token) => {
+    if (token.name.startsWith('no-')) {
+      // Store foo:false for --no-foo
+      const positiveName = token.name.slice(3);
+      values[positiveName] = false;
+      delete values[token.name];
+    } else {
+      // Resave value so last one wins if both --foo and --no-foo.
+      values[token.name] = token.value ?? true;
+    }
+  });
+
+const color = values.color;
+const logfile = values.logfile ?? 'default.log';
+
+console.log({ logfile, color });
 ```
 
-This call shows the three kinds of token and their properties:
+Example usage showing negated options, and when option use multiple times then last one wins.
 
 ```console
-$ node tokens.cjs -xy --foo=BAR -- file.txt
-{
-  values: [Object: null prototype] { d: true, foo: 'BAR' },
-  positionals: [ 'file.txt' ],
-  tokens: [
-    {
-      kind: 'option',
-      name: 'x',
-      rawName: '-x',
-      index: 0,
-      value: undefined,
-      inlineValue: undefined
-    },
-    {
-      kind: 'option',
-      name: 'y',
-      rawName: '-y',
-      index: 0,
-      value: undefined,
-      inlineValue: undefined
-    },
-    {
-      kind: 'option',
-      name: 'foo',
-      rawName: '--foo',
-      index: 1,
-      value: 'BAR',
-      inlineValue: true
-    },
-    { kind: 'option-terminator', index: 2 },
-    { kind: 'positional', index: 3, value: 'file.txt' }
-  ]
-}
+$ node negate.js
+{ logfile: 'default.log', color: undefined }
+$ node negate.js --no-logfile --no-color
+{ logfile: false, color: false }
+$ node negate.js --logfile=test.log --color
+{ logfile: 'test.log', color: true }
+$ node negate.js --no-logfile --logfile=test.log --color --no-color
+{ logfile: 'test.log', color: false }
 ```
 
-The source argument for a token is `args[token.index]`.
-Short option groups like `-xy` expand to a token for each option.
-The `x` and `y` tokens above have the same index, since
-they come from the same argument.
-
 `util.parseArgs()` is experimental and behavior may change. Join the
 conversation in [pkgjs/parseargs][] to contribute to the design.
 

examples/negate.js

@@ -7,7 +7,7 @@
 const { parseArgs } = require('..'); // in repo
 
 const options = {
-  ['color']: { type: 'string' },
+  ['color']: { type: 'boolean' },
   ['no-color']: { type: 'boolean' },
   ['logfile']: { type: 'string' },
   ['no-logfile']: { type: 'boolean' },
@@ -36,6 +36,6 @@ console.log({ logfile, color });
 
 // Try the following:
 //   node negate.js
-//   node negate.js --logfile=test.log --color=red
+//   node negate.js --logfile=test.log --color
 //   node negate.js --no-logfile --no-color
-//   node negate.js --no-logfile --logfile=test.log --color=red --no-color
+//   node negate.js --no-logfile --logfile=test.log --color --no-color