Support for macros and escaping flag values

Author: pilafmon

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,6 +61,10 @@ 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

package.json

@@ -34,6 +34,11 @@
       "node": true,
       "mocha": true
    },
+   "cliConfig": {
+      "macros": {
+         "lucky-number": "777"
+      }
+   },
    "runScriptsConfig": {
       "clean": [
          "rimraf build dist"
@@ -67,6 +72,6 @@
       "rimraf": "~6.1",
       "run-scripts-util": "~1.3",
       "typescript": "~5.9",
-      "typescript-eslint": "~8.52"
+      "typescript-eslint": "~8.54"
    }
 }

spec/mocha.spec.js

@@ -36,12 +36,15 @@ describe('Library module', () => {
       const module = cliArgvUtil;
       const actual = Object.keys(module).sort().map(key => [key, typeof module[key]]);
       const expected = [
-         ['calcAncestor', 'function'],
-         ['cleanPath',    'function'],
-         ['parse',        'function'],
-         ['readFolder',   'function'],
-         ['run',          'function'],
-         ['unquoteArgs',  'function'],
+         ['assert',          'function'],
+         ['calcAncestor',    'function'],
+         ['cleanPath',       'function'],
+         ['parse',           'function'],
+         ['readFolder',      'function'],
+         ['readPackageJson', 'function'],
+         ['run',             'function'],
+         ['unescape',        'function'],
+         ['unquoteArgs',     'function'],
          ];
       assertDeepStrictEqual(actual, expected);
       });
@@ -60,6 +63,36 @@ describe('Calling cliArgvUtil.parse()', () => {
             flag1: undefined,
             flag3: 'three',
             },
+         flagMapRaw: {
+            flag1: undefined,
+            flag3: 'three',
+            },
+         flagOn: {
+            flag1: true,
+            flag2: false,
+            flag3: true,
+            },
+         invalidFlag:    null,
+         invalidFlagMsg: null,
+         params:         ['file.html', 'file.png'],
+         paramCount:     2,
+         };
+      assertDeepStrictEqual(actual, expected);
+      });
+
+   it('with escaped characters and macros results in the correct replacements', () => {
+      const validFlags = ['flag1', 'flag2', 'flag3'];
+      mockCli('file.html --flag1={{hash}}{{space}}Allow{{space}}bots{{bang}} file.png --flag3={{macro:lucky-number}}');
+      const actual = cliArgvUtil.parse(validFlags);
+      const expected = {
+         flagMap: {
+            flag1: '# Allow bots!',
+            flag3: '777',
+            },
+         flagMapRaw: {
+            flag1: '{{hash}}{{space}}Allow{{space}}bots{{bang}}',
+            flag3: '{{macro:lucky-number}}',
+            },
          flagOn: {
             flag1: true,
             flag2: false,
@@ -82,6 +115,10 @@ describe('Calling cliArgvUtil.parse()', () => {
             flagOne:   undefined,
             flagThree: 'three',
             },
+         flagMapRaw: {
+            flagOne:   undefined,
+            flagThree: 'three',
+            },
          flagOn: {
             flagOne:   true,
             flagTwo:   false,
@@ -101,6 +138,7 @@ describe('Calling cliArgvUtil.parse()', () => {
       const actual = cliArgvUtil.parse(validFlags);
       const expected = {
          flagMap: {},
+         flagMapRaw: {},
          flagOn: {
             flag1: false,
             flag2: false,
@@ -123,6 +161,10 @@ describe('Calling cliArgvUtil.parse()', () => {
             flagOne:   undefined,
             flagThree: 't h r e e',
             },
+         flagMapRaw: {
+            flagOne:   undefined,
+            flagThree: 't h r e e',
+            },
          flagOn: {
             flagOne:   true,
             flagTwo:   false,
@@ -150,6 +192,10 @@ describe('Correct error message is generated', () => {
             bogus: undefined,
             flag3: 'three',
             },
+         flagMapRaw: {
+            bogus: undefined,
+            flag3: 'three',
+            },
          flagOn: {
             flag1: false,
             flag2: false,

src/cli-argv-util.ts

@@ -19,16 +19,83 @@ export type Ancestor = {
    message: string,          //color output in the format: "common: source -> target"
    };
 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
-   params:         string[],        //array of parameter values supplied by the user
    paramCount:     number,          //number of parameters supplied by the user
+   params:         string[],        //array of parameter values supplied by the user
    };
+type Json = string | number | boolean | null | undefined | JsonObject | Json[];
+type JsonObject = { [key: string]: Json };
 
 const cliArgvUtil = {
 
+   assert(ok: unknown, message: string | null) {
+      if (!ok)
+         throw new Error(`[replacer-util] ${message}`);
+      },
+
+   readPackageJson() {
+      // Returns package.json as an object literal.
+      const pkgExists = fs.existsSync('package.json');
+      const pkg = pkgExists ? <JsonObject>JSON.parse(fs.readFileSync('package.json', 'utf-8')) : null;
+      const fixHiddenKeys = (pkgObj: JsonObject) => {
+         const unhide = (key: string) => {
+            const newKey = key.replace(/[@./]/g, '-');
+            if (!pkgObj[newKey])
+               pkgObj[newKey] = pkgObj[key]!;
+            };
+         Object.keys(pkgObj).forEach(unhide);
+         };
+      if (pkg?.dependencies)
+         fixHiddenKeys(<JsonObject>pkg.dependencies);
+      if (pkg?.devDependencies)
+         fixHiddenKeys(<JsonObject>pkg.devDependencies);
+      return pkg;
+      },
+
+   unescape(flags: StringFlagMap): StringFlagMap {
+      // Returns a map of CLI flags with all the flag values unescaped and macros expanded.
+      // Example:
+      //    '{{hash}}{{space}}Allow{{space}}bots{{bang}}' --> '# Allow bots!'
+      const escapers: [RegExp, string][] = [
+         [/{{apos}}/g,        "'"],
+         [/{{bang}}/g,        '!'],
+         [/{{close-curly}}/g, '}'],
+         [/{{equals}}/g,      '='],
+         [/{{gt}}/g,          '>'],
+         [/{{hash}}/g,        '#'],
+         [/{{lt}}/g,          '<'],
+         [/{{open-curly}}/g,  '{'],
+         [/{{pipe}}/g,        '|'],
+         [/{{quote}}/g,       '"'],
+         [/{{semi}}/g,        ';'],
+         [/{{space}}/g,       ' '],
+         ];
+      const macroPattern = /^{{macro:(.*)}}$/;
+      const flagEntries =  Object.entries(flags);
+      const usesMacros =   flagEntries.some(entry => entry[1]?.match(macroPattern));
+      const pkg =          usesMacros ? cliArgvUtil.readPackageJson()! : {};
+      if (!pkg.cliConfig && pkg.replacerConfig)  //DEPRECATED
+         pkg.cliConfig = pkg.replacerConfig;     //backwards compatibility workaround
+      const macros =       <JsonObject | undefined>(<JsonObject | undefined>pkg.cliConfig)?.macros;
+      const unescapeOne = (flagValue: string, escaper: typeof escapers[number]) =>
+         flagValue.replace(escaper[0], escaper[1]);
+      const expandMacro = (flagValue: string) => {
+         // If param is a macro defined in package.json, return the macro's value.
+         const macroName =  <keyof JsonObject>flagValue.match(macroPattern)?.[1];
+         const macroValue = <string>macros?.[macroName];
+         const missing =    macroName && !macroValue;
+         cliArgvUtil.assert(!missing, `Macro "${macroName}" used but not defined in package.json`);
+         return macroName ? macroValue : flagValue;
+         };
+      const doReplacements = (flagValue?: string) =>
+         !flagValue ? undefined : escapers.reduce(unescapeOne, expandMacro(flagValue));
+      return Object.fromEntries(flagEntries.map(pair => [pair[0], doReplacements(pair[1])]));
+      },
+
    parse(validFlags: string[]): Result {
       const toCamel =     (token: string) =>  token.replace(/-./g, char => char[1]!.toUpperCase());  //example: 'no-map' --> 'noMap'
       const toEntry =     (pair: string[]) => [toCamel(pair[0]!), pair[1]];        //example: ['no-map'] --> ['noMap', undefined]
@@ -42,7 +109,8 @@ const cliArgvUtil = {
       const helpMsg =     '\nValid flags are --' + validFlags.join(' --');
       const params =      args.filter(arg => !/^--/.test(arg));
       return {
-         flagMap:        flagMap,
+         flagMap:        cliArgvUtil.unescape(flagMap),
+         flagMapRaw:     flagMap,
          flagOn:         flagOn,
          invalidFlag:    invalidFlag,
          invalidFlagMsg: invalidFlag ? 'Invalid flag: --' + invalidFlag + helpMsg : null,