v3.3.0-beta :: The POWER of Trigrams!!!

Author: Chinory

README.md

@@ -68,18 +68,18 @@ function main() {
 
   // Check if a subcommand was encountered (returns object with next position)
   if (typeof ret === 'object') {
-    // ret contains { i, key, opt }:
-    // - ret.i is the index to continue parsing from (already incremented)
+    // ret contains { avi, key, opt }:
+    // - ret.avi is the argv index to continue parsing from
     // - ret.key is the variable name in gitReq that triggered the exit ('command')
     // - ret.opt is the option string that triggered the exit (subcommand name)
 
     console.error(`Executing ${ret.opt} command...`);
 
     switch (ret.opt) {
       case 'commit':
-        // Parse commit-specific options starting from ret.i
+        // Parse commit-specific options starting from ret.avi
         const commitRes = {};
-        parse(process.argv, ret.i, commitReq, commitRes, console.error);
+        parse(process.argv, ret.avi, commitReq, commitRes, console.error);
 
         // Use the results
         console.error(
@@ -109,14 +109,14 @@ parse(argv, i, req, res, err)
 - **i**: Starting index for parsing (usually `2`)
 - **req**: Configuration object defining your command structure
 - **res**: Object that will be populated with parsed results
-- **err**: Error handler function, receives `{msg, i, opt, key, val}` and returns boolean
+- **err**: Error handler function, receives `{msg, avi, opt, key, val}` and returns boolean
 
 ### Return Value
 
 The function returns either:
 - A number (the next index after parsing completed normally)
-- An object `{ i, key, opt }` when exiting early due to an exit option, where:
-  - `i`: The next index to resume parsing from (already incremented past the exit option)
+- An object `{ avi, key, opt }` when exiting early due to an exit option, where:
+  - `avi`: The next index to resume parsing from (**A**rg**V** **I**ndex)
   - `key`: The variable name in the req object that triggered the exit
   - `opt`: The option string that triggered the exit (e.g., the subcommand name)
 
@@ -248,15 +248,15 @@ const ret = parse(process.argv, 2, mainReq, mainRes, console.error);
 
 if (typeof ret === 'object') {
   // When a command is found via the exit mechanism:
-  // - ret.i is already positioned after the subcommand
+  // - ret.avi is already positioned after the subcommand
   // - ret.key contains the variable name in req ('command' in this case)
   // - ret.opt contains the matched option (the subcommand name)
 
   switch(ret.opt) {
     case 'build':
       const buildReq = { /* build options */ };
       const buildRes = {};
-      parse(process.argv, ret.i, buildReq, buildRes, console.error);
+      parse(process.argv, ret.avi, buildReq, buildRes, console.error);
       break;
   }
 }

examples/cli-tool.js

@@ -99,16 +99,16 @@ function main() {
   if (typeof ret === 'object') {
     // When a command is found via the exit mechanism,
     // ret contains {i, key, opt} where:
-    // - ret.i is the index to resume parsing from
+    // - ret.avi is the index to resume parsing from
     // - ret.key is the variable name in req that triggered the exit (here: 'command')
     // - ret.opt is the value that matched (here: the command name itself)
 
     switch (ret.opt) {
       case 'build':
-        handleBuildCommand(ret.i);
+        handleBuildCommand(ret.avi);
         break;
       case 'serve':
-        handleServeCommand(ret.i);
+        handleServeCommand(ret.avi);
         break;
       case 'test':
         console.log('Running tests...');

index.js

@@ -1,23 +1,23 @@
 'use strict';
 const isA = Array.isArray;
 /**
- * @typedef {string} KeyStr Variable name
- * @typedef {string | boolean | string[]} VarVal Variable value
+ * @typedef {string} KeyStr Variable name, in most cases, or kit name
  * @typedef {string} OptStr Option string, e.g. '--', '-o', '--option'
- * @typedef {OptStr | null} OptDef Option definitions, e.g. '--', '-o', '--option', or null to refer to the variable name
- * @typedef {OptDef | OptDef[]} OptKit one or more option definitions
+ * @typedef {OptStr | null} OptDef Option definition, e.g. '--', '-o', '--option', or `null` to refer to the variable name
+ * @typedef {OptDef | OptDef[]} OptKit one or more option definitions, for a shortest one
  * 
  * @typedef {object} VarKit Variable configuration object
  * @property {VarVal} [def] Variable **def**inition & **def**ault value (pun intended)
  * @property {OptKit} [set] Array of options to set the variable value
  * @property {OptKit} [rst] Array of options to reset the variable value
+ * @typedef {string | boolean | string[]} VarVal Variable value
  * 
- * @typedef {OptDef | OptDef[]} ExitKit Exit options, identical to `OptKit` for now
- * @typedef {Record<KeyStr, VarKit | ExitKit>} KeyKitMap
- * @typedef {Record<KeyStr, VarVal>} KeyValMap
+ * @typedef {OptDef | OptDef[]} ExitKit Exit options
+ * @typedef {Record<KeyStr, VarKit | ExitKit>} KeyKitMap `req`
+ * @typedef {Record<KeyStr, VarVal>} KeyValMap `res`
  * 
  * @callback IsFatal
- * @param {{msg: string, i: number, opt: OptStr, key?: KeyStr, val?: VarVal }} err
+ * @param {{msg: string, avi: number, opt: OptStr, key?: KeyStr, val?: VarVal }} err
  * @returns {boolean} Whether the parsing should continue (false) or quit (true)
  * @typedef {Record<OptStr, KeyStr>} OptKeyMap internal type
  */
@@ -30,7 +30,7 @@ const god = ok => ok === undefined ? [] : isA(ok) ? ok : [ok];
  * @param {KeyKitMap} req Options structure definition
  * @param {KeyValMap} res Object to store parsed results
  * @param {IsFatal} err Error handler function, return true to quit parsing
- * @returns {number | { i: number, key: KeyStr, opt: OptStr }}
+ * @returns {number | { avi: number, key: KeyStr, opt: OptStr }} `ret` is object when an exit option applied, or just `avi`
  * @example
  */
 export default function parse(argv, i, req, res, err) {
@@ -52,8 +52,8 @@ export default function parse(argv, i, req, res, err) {
 			return false;
 		 } return true;
 	}, k = o => o == null ? key : o, // undefined is ok?
-	ask = (msg, val) => err({msg, i, opt, key, val}),
-	exit = c => ({ i: i + c, key, opt });
+	ask = (msg, val) => err({msg, avi: i, opt, key, val}),
+	exit = c => ({ avi: i+c, key, opt });
 	// prepare
 	/** @type {OptKeyMap} */
 	const set_ = {}, rst_ = {}, exit_ = {};

package.json

@@ -1,6 +1,6 @@
 {
   "name": "pargv-lite",
-  "version": "3.2.3-beta",
+  "version": "3.3.0-beta",
   "description": "A lightning-fast, single-pass command line argument parser with structure validation",
   "main": "index.js",
   "type": "module",

poke.js

@@ -100,18 +100,18 @@ poke('cannot exit within an argument && default named exit option', ['-abcd'], {
 🔍 { a: { def: false, set: '-a' }, b: '-b', '-c': undefined, '-d': null }
 💥 {
   msg: 'cannot exit within an argument',
-  i: 0,
+  avi: 0,
   opt: '-b',
   key: 'b',
   val: undefined
 }
 💥 {
   msg: 'invalid option',
-  i: 0,
+  avi: 0,
   opt: '-c',
   key: undefined,
   val: undefined
 }
 🎁 { a: true }
-😇 { i: 1, key: '-d', opt: '-d' }
+😇 { avi: 1, key: '-d', opt: '-d' }
 */

test.js

@@ -19,7 +19,7 @@ function runTest(name, fn) {
 
 // Error handler for tests
 const errorHandler = (err) => {
-  console.log(`   Test error: ${err.msg} at position ${err.i} for option ${err.opt}`);
+  console.log(`   Test error: ${err.msg} at position ${err.avi} for option ${err.opt}`);
   return false; // Continue parsing
 };
 
@@ -159,7 +159,7 @@ runTest('Exit options', () => {
   if (typeof ret !== 'object') throw ret;
   assert.strictEqual(ret.key, 'command');
   assert.strictEqual(ret.opt, 'build');
-  assert.strictEqual(ret.i, 3);
+  assert.strictEqual(ret.avi, 3);
 });
 
 // TEST 6: Combined short options
@@ -314,7 +314,7 @@ runTest('Exit on anonymous arguments', () => {
   if (typeof ret !== 'object') throw ret;
   assert.strictEqual(ret.key, 'files');
   assert.strictEqual(ret.opt, '1.txt');
-  assert.strictEqual(ret.i, 3);
+  assert.strictEqual(ret.avi, 3);
 });
 
 console.log('🎉 All tests completed!');