cli-argv-util 1.4.1 → 1.5.1

package/README.md

@@ -33,7 +33,7 @@ if (cli.flagOn.noSummary)
 console.info('You supplied', cli.params.length , 'CLI parameter(s).');
 ```
 For a real world example, see:
-[cli.js](https://github.com/center-key/copy-file-util/blob/main/bin/cli.js)
+[copy-file.ts](https://github.com/center-key/copy-file-util/blob/main/src/copy-file.ts)
 
 If your CLI tool is named `my-program` and a user runs it like:
 ```shell
@@ -45,6 +45,9 @@ the resulting `cli` object will be:
    flagMap: {
       cd: 'src',
       },
+   flagMapRaw: {
+      cd: 'src',
+      },
    flagOn: {
       cd:        true,
       find:      false,
@@ -58,13 +61,18 @@ the resulting `cli` object will be:
 > [!NOTE]
 > _Single quotes in commands are normalized so they work cross-platform and avoid the errors often encountered on Microsoft Windows._
 
+> [!NOTE]
+> _CLI flag values support escaped charcters and macros._<br>
+> _For documentation, see:_ https://github.com/center-key/replacer-util
+
 ## C) Results
 The `cliArgvUtil.parse()` returns an object of type `Result`:
 ```typescript
 export type StringFlagMap =  { [flag: string]: string | undefined };
 export type BooleanFlagMap = { [flag: string]: boolean };
 export type Result = {
-   flagMap:        StringFlagMap,   //map of flag values for each user supplied flag
+   flagMap:        StringFlagMap,   //map of unescaped flag values for each user supplied flag
+   flagMapRaw:     StringFlagMap,   //map of flag values for each user supplied flag
    flagOn:         BooleanFlagMap,  //map of the enabled status for all valid flags
    invalidFlag:    string | null,   //name of the first invalid flag
    invalidFlagMsg: string | null,   //error message for the invalid flag

package/dist/cli-argv-util.d.ts

@@ -1,4 +1,4 @@
-//! cli-argv-util v1.4.1 ~~ https://github.com/center-key/cli-argv-util ~~ MIT License
+//! cli-argv-util v1.5.1 ~~ https://github.com/center-key/cli-argv-util ~~ MIT License
 
 export type StringFlagMap = {
     [flag: string]: string | undefined;
@@ -16,13 +16,25 @@ export type Ancestor = {
 };
 export type Result = {
     flagMap: StringFlagMap;
+    flagMapRaw: StringFlagMap;
     flagOn: BooleanFlagMap;
     invalidFlag: string | null;
     invalidFlagMsg: string | null;
-    params: string[];
     paramCount: number;
+    params: string[];
+};
+type Json = string | number | boolean | null | undefined | JsonObject | Json[];
+type JsonObject = {
+    [key: string]: Json;
 };
 declare const cliArgvUtil: {
+    assert(ok: unknown, message: string | null): void;
+    readPackageJson(): JsonObject;
+    escapers: {
+        regex: RegExp;
+        char: string;
+    }[];
+    unescape(text: string, pkg: JsonObject): string;
     parse(validFlags: string[]): Result;
     run(packageJson: {
         [key: string]: unknown;

package/dist/cli-argv-util.js

@@ -1,4 +1,4 @@
-//! cli-argv-util v1.4.1 ~~ https://github.com/center-key/cli-argv-util ~~ MIT License
+//! cli-argv-util v1.5.1 ~~ https://github.com/center-key/cli-argv-util ~~ MIT License
 
 import { execSync } from 'node:child_process';
 import chalk from 'chalk';
@@ -6,20 +6,75 @@ import fs from 'fs';
 import path from 'path';
 import slash from 'slash';
 const cliArgvUtil = {
+    assert(ok, message) {
+        if (!ok)
+            throw new Error(`[replacer-util] ${message}`);
+    },
+    readPackageJson() {
+        const pkgFile = 'package.json';
+        const getPkg = () => JSON.parse(fs.readFileSync(pkgFile, 'utf-8'));
+        const pkg = fs.existsSync(pkgFile) ? getPkg() : {};
+        const fixHiddenKeys = (pkgObj) => {
+            const unhide = (key) => {
+                const newKey = key.replace(/[@./]/g, '-');
+                if (!pkgObj[newKey])
+                    pkgObj[newKey] = pkgObj[key];
+            };
+            Object.keys(pkgObj).forEach(unhide);
+        };
+        if (pkg.dependencies)
+            fixHiddenKeys(pkg.dependencies);
+        if (pkg.devDependencies)
+            fixHiddenKeys(pkg.devDependencies);
+        if (!pkg.cliConfig && pkg.replacerConfig)
+            pkg.cliConfig = pkg.replacerConfig;
+        return pkg;
+    },
+    escapers: [
+        { regex: /{{apos}}/g, char: "'" },
+        { regex: /{{bang}}/g, char: '!' },
+        { regex: /{{close-curly}}/g, char: '}' },
+        { regex: /{{equals}}/g, char: '=' },
+        { regex: /{{gt}}/g, char: '>' },
+        { regex: /{{hash}}/g, char: '#' },
+        { regex: /{{lt}}/g, char: '<' },
+        { regex: /{{open-curly}}/g, char: '{' },
+        { regex: /{{pipe}}/g, char: '|' },
+        { regex: /{{quote}}/g, char: '"' },
+        { regex: /{{semi}}/g, char: ';' },
+        { regex: /{{space}}/g, char: ' ' },
+    ],
+    unescape(text, pkg) {
+        const macroPattern = /^{{macro:(.*)}}$/;
+        const macros = (pkg.cliConfig?.macros ?? {});
+        const macroName = text.match(macroPattern)?.[1];
+        const macroValue = macros[macroName];
+        const expandedText = macroName ? macroValue : text;
+        const missing = macroName && !macroValue;
+        cliArgvUtil.assert(!missing, `Macro "${macroName}" used but not defined in package.json`);
+        const replace = (flagValue, escaper) => flagValue.replace(escaper.regex, escaper.char);
+        return cliArgvUtil.escapers.reduce(replace, expandedText);
+    },
     parse(validFlags) {
+        const pkg = cliArgvUtil.readPackageJson();
         const toCamel = (token) => token.replace(/-./g, char => char[1].toUpperCase());
         const toEntry = (pair) => [toCamel(pair[0]), pair[1]];
         const toPair = (flag) => flag.replace(/^--/, '').split('=');
+        const unescape = (value) => !value ? undefined : cliArgvUtil.unescape(value, pkg);
         const args = cliArgvUtil.unquoteArgs(process.argv.slice(2));
         const pairs = args.filter(arg => /^--/.test(arg)).map(toPair);
-        const flagMap = Object.fromEntries(pairs.map(toEntry));
-        const onEntries = validFlags.map(flag => [toCamel(flag), toCamel(flag) in flagMap]);
+        const flagMapRaw = Object.fromEntries(pairs.map(toEntry));
+        const flagEntries = Object.entries(flagMapRaw);
+        const flagMap = Object.fromEntries(flagEntries.map(pair => [pair[0], unescape(pair[1])]));
+        const onEntries = validFlags.map(flag => [toCamel(flag), toCamel(flag) in flagMapRaw]);
         const flagOn = Object.fromEntries(onEntries);
         const invalidFlag = pairs.find(pair => !validFlags.includes(pair[0]))?.[0] ?? null;
         const helpMsg = '\nValid flags are --' + validFlags.join(' --');
-        const params = args.filter(arg => !/^--/.test(arg));
+        const rawParams = args.filter(arg => !/^--/.test(arg));
+        const params = rawParams.map(param => cliArgvUtil.unescape(param, pkg));
         return {
             flagMap: flagMap,
+            flagMapRaw: flagMapRaw,
             flagOn: flagOn,
             invalidFlag: invalidFlag,
             invalidFlagMsg: invalidFlag ? 'Invalid flag: --' + invalidFlag + helpMsg : null,

package/package.json

@@ -1,6 +1,6 @@
 {
    "name": "cli-argv-util",
-   "version": "1.4.1",
+   "version": "1.5.1",
    "description": "Simple utility to parse command line parameters and flags (arguments vector)",
    "license": "MIT",
    "type": "module",
@@ -34,6 +34,13 @@
       "node": true,
       "mocha": true
    },
+   "cliConfig": {
+      "macros": {
+         "html-filename": "file.html",
+         "png-filename": "file.png",
+         "lucky-number": "777"
+      }
+   },
    "runScriptsConfig": {
       "clean": [
          "rimraf build dist"
@@ -56,17 +63,17 @@
       "slash": "~5.1"
    },
    "devDependencies": {
-      "@eslint/js": "~9.39",
-      "@types/node": "~25.0",
+      "@eslint/js": "~10.0",
+      "@types/node": "~25.5",
       "add-dist-header": "~1.6",
       "assert-deep-strict-equal": "~1.2",
       "copy-file-util": "~1.3",
-      "eslint": "~9.39",
+      "eslint": "~10.1",
       "jshint": "~2.13",
       "mocha": "~11.7",
       "rimraf": "~6.1",
       "run-scripts-util": "~1.3",
       "typescript": "~5.9",
-      "typescript-eslint": "~8.52"
+      "typescript-eslint": "~8.57"
    }
 }