Use negate as example for tokens. Rework description a little.

nodejs · nodejs-github-bot · Jul 18, 2022 · Jun 17, 2022 · Jul 4, 2022 · Jul 4, 2022
commit fb2cd00dc457c7459615fd3babe018c55bc7daf3
diff --git a/doc/api/util.md b/doc/api/util.md
@@ -1102,79 +1102,109 @@ 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`.
   * `value` { string | undefined } Option value specified in args.
-    Undefined for boolean options.
+Undefined for boolean options.
   * `inlineValue` { boolean | undefined } Whether option value specified inline,
-    like `--foo=bar`.
+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.