cli-argv-util 1.4.0 → 1.5.0

package/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022-2025 Individual contributors to cli-argv-util
+Copyright (c) 2022-2026 Individual contributors to cli-argv-util
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

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.0 ~~ https://github.com/center-key/cli-argv-util ~~ MIT License
+//! cli-argv-util v1.5.0 ~~ https://github.com/center-key/cli-argv-util ~~ MIT License
 
 export type StringFlagMap = {
     [flag: string]: string | undefined;
@@ -10,17 +10,27 @@ export type Ancestor = {
     common: string;
     source: string;
     target: string;
+    renamed: boolean;
+    filename: string | null;
     message: string;
 };
 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 | null;
+    unescape(flags: StringFlagMap): StringFlagMap;
     parse(validFlags: string[]): Result;
     run(packageJson: {
         [key: string]: unknown;

package/dist/cli-argv-util.js

@@ -1,4 +1,4 @@
-//! cli-argv-util v1.4.0 ~~ https://github.com/center-key/cli-argv-util ~~ MIT License
+//! cli-argv-util v1.5.0 ~~ https://github.com/center-key/cli-argv-util ~~ MIT License
 
 import { execSync } from 'node:child_process';
 import chalk from 'chalk';
@@ -6,6 +6,60 @@ 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 pkgExists = fs.existsSync('package.json');
+        const pkg = pkgExists ? JSON.parse(fs.readFileSync('package.json', 'utf-8')) : null;
+        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);
+        return pkg;
+    },
+    unescape(flags) {
+        const escapers = [
+            [/{{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)
+            pkg.cliConfig = pkg.replacerConfig;
+        const macros = pkg.cliConfig?.macros;
+        const unescapeOne = (flagValue, escaper) => flagValue.replace(escaper[0], escaper[1]);
+        const expandMacro = (flagValue) => {
+            const macroName = flagValue.match(macroPattern)?.[1];
+            const macroValue = 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) => !flagValue ? undefined : escapers.reduce(unescapeOne, expandMacro(flagValue));
+        return Object.fromEntries(flagEntries.map(pair => [pair[0], doReplacements(pair[1])]));
+    },
     parse(validFlags) {
         const toCamel = (token) => token.replace(/-./g, char => char[1].toUpperCase());
         const toEntry = (pair) => [toCamel(pair[0]), pair[1]];
@@ -19,7 +73,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,
@@ -46,8 +101,12 @@ const cliArgvUtil = {
         const source = sourceFile.substring(len);
         const target = targetFile.substring(len);
         const intro = common ? chalk.blue(common) + chalk.gray.bold(': ') : '';
-        const message = intro + chalk.white(source) + chalk.gray.bold(' → ') + chalk.green(target);
-        return { common, source, target, message };
+        const renamed = path.basename(sourceFile) !== path.basename(targetFile);
+        const filename = renamed ? null : path.basename(sourceFile);
+        const folder = path.dirname(target);
+        const dest = renamed ? target : (folder === '.' ? filename : folder + '/');
+        const message = intro + chalk.white(source) + chalk.gray.bold(' → ') + chalk.green(dest);
+        return { common, source, target, renamed, filename, message };
     },
     unquoteArgs(args) {
         const unquote = (builder, nextArg) => {

package/package.json

@@ -1,6 +1,6 @@
 {
    "name": "cli-argv-util",
-   "version": "1.4.0",
+   "version": "1.5.0",
    "description": "Simple utility to parse command line parameters and flags (arguments vector)",
    "license": "MIT",
    "type": "module",
@@ -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.49"
+      "typescript-eslint": "~8.54"
    }
 }