feat: add parsed meta-data to returned properties

index.js

@@ -4,7 +4,6 @@ const {
   ArrayPrototypeForEach,
   ArrayPrototypeIncludes,
   ArrayPrototypePush,
-  ArrayPrototypePushApply,
   ArrayPrototypeShift,
   ArrayPrototypeSlice,
   ArrayPrototypeUnshiftApply,
@@ -13,6 +12,7 @@ const {
   StringPrototypeCharAt,
   StringPrototypeIndexOf,
   StringPrototypeSlice,
+  StringPrototypeStartsWith,
 } = require('./primordials');
 
 const {
@@ -64,19 +64,18 @@ function getMainArgs() {
 /**
  * In strict mode, throw for possible usage errors like --foo --bar
  *
- * @param {string} longOption - long option name e.g. 'foo'
- * @param {string|undefined} optionValue - value from user args
- * @param {string} shortOrLong - option used, with dashes e.g. `-l` or `--long`
- * @param {boolean} strict - show errors, from parseArgs({ strict })
+ * @param {object} config - from config passed to parseArgs
+ * @param {object} element- array item from parseElements returned by parseArgs
  */
-function checkOptionLikeValue(longOption, optionValue, shortOrLong, strict) {
-  if (strict && isOptionLikeValue(optionValue)) {
+function checkOptionLikeValue(config, element) {
+  if (config.strict && (element.kind === 'option') &&
+    (element.inlineValue === false) && isOptionLikeValue(element.value)) {
     // Only show short example if user used short option.
-    const example = (shortOrLong.length === 2) ?
-      `'--${longOption}=-XYZ' or '${shortOrLong}-XYZ'` :
-      `'--${longOption}=-XYZ'`;
-    const errorMessage = `Option '${shortOrLong}' argument is ambiguous.
-Did you forget to specify the option argument for '${shortOrLong}'?
+    const example = StringPrototypeStartsWith(element.optionUsed, '--') ?
+      `'${element.optionUsed}=-XYZ'` :
+      `'--${element.optionName}=-XYZ' or '${element.optionUsed}-XYZ'`;
+    const errorMessage = `Option '${element.optionUsed}' argument is ambiguous.
+Did you forget to specify the option argument for '${element.optionUsed}'?
 To specify an option argument starting with a dash use ${example}.`;
     throw new ERR_PARSE_ARGS_INVALID_OPTION_VALUE(errorMessage);
   }
@@ -85,63 +84,59 @@ To specify an option argument starting with a dash use ${example}.`;
 /**
  * In strict mode, throw for usage errors.
  *
- * @param {string} longOption - long option name e.g. 'foo'
- * @param {string|undefined} optionValue - value from user args
- * @param {object} options - option configs, from parseArgs({ options })
- * @param {string} shortOrLong - option used, with dashes e.g. `-l` or `--long`
- * @param {boolean} strict - show errors, from parseArgs({ strict })
- * @param {boolean} allowPositionals - from parseArgs({ allowPositionals })
+ * @param {object} config - from config passed to parseArgs
+ * @param {object} element- array item from parseElements returned by parseArgs
  */
-function checkOptionUsage(longOption, optionValue, options,
-                          shortOrLong, strict, allowPositionals) {
-  // Strict and options are used from local context.
-  if (!strict) return;
+function checkOptionUsage(config, element) {
+  if (!config.strict) return;
 
-  if (!ObjectHasOwn(options, longOption)) {
-    throw new ERR_PARSE_ARGS_UNKNOWN_OPTION(shortOrLong, allowPositionals);
+  if (!ObjectHasOwn(config.options, element.optionName)) {
+    throw new ERR_PARSE_ARGS_UNKNOWN_OPTION(
+      element.optionUsed, config.allowPositionals);
   }
 
-  const short = optionsGetOwn(options, longOption, 'short');
-  const shortAndLong = short ? `-${short}, --${longOption}` : `--${longOption}`;
-  const type = optionsGetOwn(options, longOption, 'type');
-  if (type === 'string' && typeof optionValue !== 'string') {
+  const short = optionsGetOwn(config.options, element.optionName, 'short');
+  const shortAndLong = `${short ? `-${short}, ` : ''}--${element.optionName}`;
+  const type = optionsGetOwn(config.options, element.optionName, 'type');
+  if (type === 'string' && typeof element.value !== 'string') {
     throw new ERR_PARSE_ARGS_INVALID_OPTION_VALUE(`Option '${shortAndLong} <value>' argument missing`);
   }
   // (Idiomatic test for undefined||null, expecting undefined.)
-  if (type === 'boolean' && optionValue != null) {
+  if (type === 'boolean' && element.value != null) {
     throw new ERR_PARSE_ARGS_INVALID_OPTION_VALUE(`Option '${shortAndLong}' does not take an argument`);
   }
 }
 
+
 /**
  * Store the option value in `values`.
  *
- * @param {string} longOption - long option name e.g. 'foo'
+ * @param {string} optionName - long option name e.g. 'foo'
  * @param {string|undefined} optionValue - value from user args
  * @param {object} options - option configs, from parseArgs({ options })
  * @param {object} values - option values returned in `values` by parseArgs
  */
-function storeOption(longOption, optionValue, options, values) {
-  if (longOption === '__proto__') {
+function storeOption(optionName, optionValue, options, values) {
+  if (optionName === '__proto__') {
     return; // No. Just no.
   }
 
   // We store based on the option value rather than option type,
   // preserving the users intent for author to deal with.
   const newValue = optionValue ?? true;
-  if (optionsGetOwn(options, longOption, 'multiple')) {
+  if (optionsGetOwn(options, optionName, 'multiple')) {
     // Always store value in array, including for boolean.
-    // values[longOption] starts out not present,
+    // values[optionName] starts out not present,
     // first value is added as new array [newValue],
     // subsequent values are pushed to existing array.
     // (note: values has null prototype, so simpler usage)
-    if (values[longOption]) {
-      ArrayPrototypePush(values[longOption], newValue);
+    if (values[optionName]) {
+      ArrayPrototypePush(values[optionName], newValue);
     } else {
-      values[longOption] = [newValue];
+      values[optionName] = [newValue];
     }
   } else {
-    values[longOption] = newValue;
+    values[optionName] = newValue;
   }
 }
 
@@ -150,6 +145,7 @@ const parseArgs = (config = { __proto__: null }) => {
   const strict = objectGetOwn(config, 'strict') ?? true;
   const allowPositionals = objectGetOwn(config, 'allowPositionals') ?? !strict;
   const options = objectGetOwn(config, 'options') ?? { __proto__: null };
+  const parseConfig = { args, strict, options, allowPositionals };
 
   // Validate input configuration.
   validateArray(args, 'args');
@@ -182,45 +178,47 @@ const parseArgs = (config = { __proto__: null }) => {
     }
   );
 
-  const result = {
-    values: { __proto__: null },
-    positionals: []
-  };
+  const elements = [];
+  let index = -1;
+  let groupCount = 0;
 
   const remainingArgs = ArrayPrototypeSlice(args);
   while (remainingArgs.length > 0) {
     const arg = ArrayPrototypeShift(remainingArgs);
     const nextArg = remainingArgs[0];
+    if (groupCount > 0)
+      groupCount--;
+    else
+      index++;
 
     // Check if `arg` is an options terminator.
     // Guideline 10 in https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
     if (arg === '--') {
-      if (!allowPositionals && remainingArgs.length > 0) {
-        throw new ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL(nextArg);
-      }
-
       // Everything after a bare '--' is considered a positional argument.
-      ArrayPrototypePushApply(
-        result.positionals,
-        remainingArgs
-      );
+      ArrayPrototypePush(elements, { kind: 'option-terminator', index });
+      ArrayPrototypeForEach(remainingArgs, (arg) =>
+        ArrayPrototypePush(
+          elements,
+          { kind: 'positional', index: ++index, value: arg }));
       break; // Finished processing args, leave while loop.
     }
 
     if (isLoneShortOption(arg)) {
       // e.g. '-f'
       const shortOption = StringPrototypeCharAt(arg, 1);
-      const longOption = findLongOptionForShort(shortOption, options);
-      let optionValue;
-      if (optionsGetOwn(options, longOption, 'type') === 'string' &&
+      const optionName = findLongOptionForShort(shortOption, options);
+      let value;
+      let inlineValue;
+      if (optionsGetOwn(options, optionName, 'type') === 'string' &&
           isOptionValue(nextArg)) {
         // e.g. '-f', 'bar'
-        optionValue = ArrayPrototypeShift(remainingArgs);
-        checkOptionLikeValue(longOption, optionValue, arg, strict);
+        value = ArrayPrototypeShift(remainingArgs);
+        inlineValue = false;
       }
-      checkOptionUsage(longOption, optionValue, options,
-                       arg, strict, allowPositionals);
-      storeOption(longOption, optionValue, options, result.values);
+      ArrayPrototypePush(
+        elements,
+        { kind: 'option', optionName, optionUsed: arg,
+          index, value, inlineValue });
       continue;
     }
 
@@ -229,8 +227,8 @@ const parseArgs = (config = { __proto__: null }) => {
       const expanded = [];
       for (let index = 1; index < arg.length; index++) {
         const shortOption = StringPrototypeCharAt(arg, index);
-        const longOption = findLongOptionForShort(shortOption, options);
-        if (optionsGetOwn(options, longOption, 'type') !== 'string' ||
+        const optionName = findLongOptionForShort(shortOption, options);
+        if (optionsGetOwn(options, optionName, 'type') !== 'string' ||
           index === arg.length - 1) {
           // Boolean option, or last short in group. Well formed.
           ArrayPrototypePush(expanded, `-${shortOption}`);
@@ -242,53 +240,78 @@ const parseArgs = (config = { __proto__: null }) => {
         }
       }
       ArrayPrototypeUnshiftApply(remainingArgs, expanded);
+      groupCount = expanded.length;
       continue;
     }
 
     if (isShortOptionAndValue(arg, options)) {
       // e.g. -fFILE
       const shortOption = StringPrototypeCharAt(arg, 1);
-      const longOption = findLongOptionForShort(shortOption, options);
-      const optionValue = StringPrototypeSlice(arg, 2);
-      checkOptionUsage(longOption, optionValue, options, `-${shortOption}`, strict, allowPositionals);
-      storeOption(longOption, optionValue, options, result.values);
+      const optionName = findLongOptionForShort(shortOption, options);
+      const value = StringPrototypeSlice(arg, 2);
+      ArrayPrototypePush(
+        elements,
+        { kind: 'option', optionName, optionUsed: `-${shortOption}`,
+          index, value, inlineValue: true });
       continue;
     }
 
     if (isLoneLongOption(arg)) {
       // e.g. '--foo'
-      const longOption = StringPrototypeSlice(arg, 2);
-      let optionValue;
-      if (optionsGetOwn(options, longOption, 'type') === 'string' &&
+      const optionName = StringPrototypeSlice(arg, 2);
+      let value;
+      let inlineValue;
+      if (optionsGetOwn(options, optionName, 'type') === 'string' &&
           isOptionValue(nextArg)) {
         // e.g. '--foo', 'bar'
-        optionValue = ArrayPrototypeShift(remainingArgs);
-        checkOptionLikeValue(longOption, optionValue, arg, strict);
+        value = ArrayPrototypeShift(remainingArgs);
+        inlineValue = false;
       }
-      checkOptionUsage(longOption, optionValue, options,
-                       arg, strict, allowPositionals);
-      storeOption(longOption, optionValue, options, result.values);
+      ArrayPrototypePush(
+        elements,
+        { kind: 'option', optionName, optionUsed: arg,
+          index, value, inlineValue });
       continue;
     }
 
     if (isLongOptionAndValue(arg)) {
       // e.g. --foo=bar
       const index = StringPrototypeIndexOf(arg, '=');
-      const longOption = StringPrototypeSlice(arg, 2, index);
-      const optionValue = StringPrototypeSlice(arg, index + 1);
-      checkOptionUsage(longOption, optionValue, options, `--${longOption}`, strict, allowPositionals);
-      storeOption(longOption, optionValue, options, result.values);
+      const optionName = StringPrototypeSlice(arg, 2, index);
+      const value = StringPrototypeSlice(arg, index + 1);
+      ArrayPrototypePush(
+        elements,
+        { kind: 'option', optionName, optionUsed: `--${optionName}`,
+          index, value, inlineValue: true });
       continue;
     }
 
-    // Anything left is a positional
-    if (!allowPositionals) {
-      throw new ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL(arg);
-    }
-
-    ArrayPrototypePush(result.positionals, arg);
+    ArrayPrototypePush(elements, { kind: 'positional', index, value: arg });
   }
 
+  const result = {
+    values: { __proto__: null },
+    positionals: [],
+    // tokens: elements,
+  };
+  ArrayPrototypeForEach(elements, (element) => {
+    switch (element.kind) {
+      case 'option-terminator':
+        break;
+      case 'positional':
+        if (!allowPositionals) {
+          throw new ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL(element.value);
+        }
+        ArrayPrototypePush(result.positionals, element.value);
+        break;
+      case 'option':
+        checkOptionUsage(parseConfig, element);
+        checkOptionLikeValue(parseConfig, element);
+        storeOption(element.optionName, element.value, options, result.values);
+        break;
+    }
+  });
+
   return result;
 };