docs: add example uses of tokens

examples/limit-long-syntax.js

@@ -0,0 +1,35 @@
+'use strict';
+
+// This is an example of using tokens to add a custom behaviour.
+//
+// Require the use of `=` for long options and values by blocking
+// the use of space separated values.
+// So allow `--foo=bar`, and not allow `--foo bar`.
+//
+// Note: this is not a common behaviour, most CLIs allow both forms.
+
+// 1. const { parseArgs } = require('node:util'); // from node
+// 2. const { parseArgs } = require('@pkgjs/parseargs'); // from package
+const { parseArgs } = require('..'); // in repo
+
+const options = {
+  file: { short: 'f', type: 'string' },
+  log: { type: 'string' },
+};
+
+const { values, tokens } = parseArgs({ options, tokens: true });
+
+const badToken = tokens.find((token) => token.kind === 'option' &&
+  token.value != null &&
+  token.rawName.startsWith('--') &&
+  !token.inlineValue
+);
+if (badToken) {
+  throw new Error(`Option value for '${badToken.rawName}' must be inline, like '${badToken.rawName}=VALUE'`);
+}
+
+console.log(values);
+
+// Try the following:
+//    node limit-long-syntax.js -f FILE --log=LOG
+//    node limit-long-syntax.js --file FILE

examples/no-repeated-options.js

@@ -0,0 +1,31 @@
+'use strict';
+
+// This is an example of using tokens to add a custom behaviour.
+//
+// Throw an error if an option is used more than once.
+
+// 1. const { parseArgs } = require('node:util'); // from node
+// 2. const { parseArgs } = require('@pkgjs/parseargs'); // from package
+const { parseArgs } = require('..'); // in repo
+
+const options = {
+  ding: { type: 'boolean', short: 'd' },
+  beep: { type: 'boolean', short: 'b' }
+};
+const { values, tokens } = parseArgs({ options, tokens: true });
+
+const seenBefore = new Set();
+tokens.forEach((token) => {
+  if (token.kind !== 'option') return;
+  if (seenBefore.has(token.name)) {
+    throw new Error(`option '${token.name}' used multiple times`);
+  }
+  seenBefore.add(token.name);
+});
+
+console.log(values);
+
+// Try the following:
+//    node no-repeated-options --ding --beep
+//    node no-repeated-options --beep -b
+//    node no-repeated-options -ddd

examples/ordered-options.mjs

@@ -0,0 +1,41 @@
+// This is an example of using tokens to add a custom behaviour.
+//
+// This adds a option order check so that --some-unstable-option
+// may only be used after --enable-experimental-options
+//
+// Note: this is not a common behaviour, the order of different options
+// does not usually matter.
+
+import { parseArgs } from '../index.js';
+
+function findTokenIndex(tokens, target) {
+  return tokens.findIndex((token) => token.kind === 'option' &&
+    token.name === target
+  );
+}
+
+const experimentalName = 'enable-experimental-options';
+const unstableName = 'some-unstable-option';
+
+const options = {
+  [experimentalName]: { type: 'boolean' },
+  [unstableName]: { type: 'boolean' },
+};
+
+const { values, tokens } = parseArgs({ options, tokens: true });
+
+const experimentalIndex = findTokenIndex(tokens, experimentalName);
+const unstableIndex = findTokenIndex(tokens, unstableName);
+if (unstableIndex !== -1 &&
+  ((experimentalIndex === -1) || (unstableIndex < experimentalIndex))) {
+  throw new Error(`'--${experimentalName}' must be specified before '--${unstableName}'`);
+}
+
+console.log(values);
+
+/* eslint-disable max-len */
+// Try the following:
+//    node ordered-options.mjs
+//    node ordered-options.mjs --some-unstable-option
+//    node ordered-options.mjs --some-unstable-option --enable-experimental-options
+//    node ordered-options.mjs --enable-experimental-options --some-unstable-option