\n\n_Find and replace strings, regex patterns, or template outputs in text files (CLI tool designed for use in npm package.json scripts)_\n\n[](https://github.com/center-key/replacer-util/blob/main/LICENSE.txt)\n[](https://www.npmjs.com/package/replacer-util)\n[](https://github.com/center-key/replacer-util/actions/workflows/run-spec-on-push.yaml)\n\n**replacer-util** searches for text to substitute with a replacement string or with values from your project's **package.json** file, such as the project version number. \nIt can also insert path metadata and concatenate output to generate content such as an HTML file of `
\n\n## A) Setup\nInstall package for node:\n```shell\n$ npm install --save-dev replacer-util\n```\n\n## B) Usage\n### 1. Synopsis\n```\nreplacer [SOURCE] [TARGET]\n```\nParameters:\n* The **first** parameter is the *source* folder or file.\n* The **second** parameter is the *target* folder.\n\n### 2. npm package.json scripts\nRun `replacer` from the `\"scripts\"` section of your **package.json** file.\n\nExample **package.json** scripts:\n```json\n \"scripts\": {\n \"build-web\": \"replacer src/web --ext=.html dist/website\",\n \"poetry\": \"replacer poems --find=human --replacement=robot dystopian-poems\"\n },\n```\nIn addition to the `--find` and `--replacement` CLI flags, template outputs in the source files will be replaced with their corresponding template variable values. \nThe template variable `package` points to the **package.json** object, enabling `{{package.version}}` in the source file to be replaced with the project's version number.\n\n### 3. Command-line npx\nExample terminal commands:\n```shell\n$ npm install --save-dev replacer-util\n$ npx replacer src/web ext=.html docs/api-manual\n```\nYou can also install **replacer-util** globally (`--global`) and then run it anywhere directly from the terminal.\n\n### 4. CLI flags\nCommand-line flags:\n| Flag | Description | Value |\n| ----------------- | ----------------------------------------------------- | ---------- |\n| `--cd` | Change working directory before starting search. | **string** |\n| `--concat` | Merge all files into one file in the target folder. | **string** |\n| `--content` | String to be used instead of the input file contents. | **string** |\n| `--exclude` | Skip files containing the string in their path. | **string** |\n| `--ext` | Filter files by file extension, such as `.js`.Use a comma to specify multiple extensions. | **string** |\n| `--find` | Text to search for in the source input files. | **string** |\n| `--header` | Prepend a line of text to each file. | **string** |\n| `--no-liquid` | Turn off LiquidJS templating. | N/A |\n| `--no-source-map` | Remove any `sourceMappingURL` comment directives. | N/A |\n| `--non-recursive` | Only read files in the source folder not subfolders. | N/A |\n| `--note` | Place to add a comment only for humans. | **string** |\n| `--quiet` | Suppress informational messages. | N/A |\n| `--regex` | Pattern to search for in the source input files. | **string** |\n| `--rename` | New output filename. | **string** |\n| `--replacement` | Text to insert into the target output files. | **string** |\n| `--summary` | Only print out the single line summary message. | N/A |\n| `--title-sort` | Ignore leading articles in `--concat` filenames. | N/A |\n| `--virtual-input` | Do not read any files, use `--content` instead. | N/A |\n\nTo avoid issues on the command line, problematic characters can be _\"escaped\"_ with safe strings as listed below.\n\nEscape characters:\n| Character | Safe stand-in string |\n| --------- | -------------------- |\n| `'` | `{{apos}}` |\n| `!` | `{{bang}}` |\n| `}` | `{{close-curly}}` |\n| `=` | `{{equals}}` |\n| `>` | `{{gt}}` |\n| `#` | `{{hash}}` |\n| `<` | `{{lt}}` |\n| `{` | `{{open-curly}}` |\n| `\\|` | `{{pipe}}` |\n| `\"` | `{{quote}}` |\n| `;` | `{{semi}}` |\n| ` ` | `{{space}}` |\n\nAlternatively, escaping for the command line can be avoided with [macros](#9-macros) you define in your project's **package.json** file (see documentation below).\n\n### 5. Examples\n - `replacer src build`
\n Recursively copies all the files in the **src** folder to the **build** folder using the data in **package.json** to update the template outputs.\n\n - `replacer src/docs --ext=.md --find=Referer --replacement=Referrer output/fixed`
\n Fixes spelling error in markdown files.\n\n - `replacer src/docs --ext=.md --find=Referer --replacement=Referrer --no-liquid output/fixed`
\n Same as previous example but disables LiquidJS templating (useful in case source files contain characters inadvertently interpreted at templating commands).\n\n - `replacer web '--find=cat dog' '--replacement= cat{{pipe}}dog ' target`
\n `replacer web --find=cat\\ dog --replacement=\\ cat{{pipe}}dog\\ target`
\n `replacer web --find=cat{{space}}dog --replacement={{space}}cat{{pipe}}dog{{space}} target`
\n Replaces all occurances of the string `'cat dog'` with `' cat|dog '` (note the _3 different_ ways to _\"escape\"_ a space character).\n\n - `replacer src --ext=.js --no-liquid --concat=bundle.js build`
\n Merges all JS files into **build/bundle.js**.\n\n - `replacer app/widgets --ext=.less --content=@import{{space}}{{quote}}{{file.dir}}/{{file.name}}{{quote}}{{semi}} --concat=widgets.less app/style`
\n Creates a single LESS file that imports the LESS files of every widget component.\n\n - `replacer app/widgets --ext=.less --content={{macro:less-import}} --concat=widgets.less app/style`
\n Identical to the previous command assuming the `less-import` macro is properly defined in the **package.json** file.\n\n - `replacer src --summary build`
\n Displays the summary informaion but not informaion about individual files copied.\n\n - `replacer src --regex=/^--/gm --replacement=🥕🥕🥕 build`
\n Finds double dashes at the start of lines and replace them with 3 carrots. \n Note the `g` and `m` [regex options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#advanced_searching_with_flags).\n\n - `replacer build/my-app.js --rename=my-app.browser.js build`
\n Copies **my-app.js** to **my-app.browser.js** without making and changes.\n\n - `replacer src/web --ext=.html --rename=index.html dist/website`
\n Renames all HTML files, such as **src/web/about/about.html**, to **index.html** while preserving the folder structure.\n\n - `replacer --cd=spec fixtures/web --find=insect --replacement=A.I. target/web`
\n Removes all insects. See: [fixtures/web/mock1.html](spec/fixtures/web/mock1.html) and [target/web/mock1.html](spec/target/exclude/mock1.html)\n\n - `replacer node_modules/chart.js/dist/chart.umd.js --no-source-map build/1-pre/libs`
\n Removes the `//# sourceMappingURL=chart.umd.js.map` line at the bottom of the **Chart.js** distribution file.\n\n - `replacer . docs --rename=robots.txt --virtual-input --content={{hash}}{{space}}Allow{{space}}bots{{bang}}`
\n Creates a **robots.txt** file with the line `# Allow bots!` in the **docs** folder.\n\n - `replacer --virtual-input . --rename=CNAME docs --content=example.com`
\n Creates a **CNAME** file with the line `example.com` in the **docs** folder.\n\nFor examples of using `replacer` as part of front-end build process, check out the `\"runScriptsConfig\"` section of:
\nhttps://github.com/dna-dom/data-dashboard/blob/main/package.json\n\n> [!NOTE]\n> _Single quotes in commands are normalized so they work cross-platform and avoid the errors often encountered on Microsoft Windows._\n\n### 6. Template outputs and filter formatters\nThe source files are processed by LiquidJS, so you can use [template outputs](https://liquidjs.com/tutorials/intro-to-liquid.html#Outputs) and [filter formatters](https://liquidjs.com/filters/overview.html). \nCustom variables are created with the [assign](ttps://liquidjs.com/tags/assign.html) tag.\n\nThree special variables are available by default:\n * `file` ([path](https://nodejs.org/api/path.html#pathparsepath) and date information about the source file)\n * `package` (values from your project's **package.json** file)\n * `webRoot` (relative path to root folder: `.`, `..`, `../..`, `../../..`, etc.)\n\nFor example, a TypeScript file with the lines:\n```typescript\nconst msg1: string = 'The current release of {{package.name | upcase}} is v{{package.version}}.';\nconst msg2: string = 'This file is: {{file.base}}';\n```\nwill be transformed into something like:\n```typescript\nconst msg1: string = 'The current release of MY-COOL-NPM-PACKAGE is v1.2.3.';\nconst msg2: string = 'This file is: my-app.ts';\n```\n\nExample outputs and formatters:\n| Source file text | Example output value | Note |\n| ------------------------------ | -------------------------- | ---------------------------------------------- |\n| `{{package.name}}` | `my-project` | Value from `name` field in **package.json** |\n| `{{package.version}}` | `3.1.4` | Value from `version` field in **package.json** |\n| `{{package.version\\|size}}` | `5` | Length of the version number string |\n| `{{file.path}}` | `src/web/sign-in.html` | Full path to source file |\n| `{{file.folder}}` | `web` | Name of parent folder of the source file |\n| `{{file.base}}` | `sign-in.html` | Source filename with the file extension |\n| `{{file.name}}` | `sign-in` | Source filename without the file extension |\n| `{{file.ext}}` | `.html` | File extension of the source file |\n| `{{file.modified}}` | `April 7, 2030` | Formatted date of when file was last modifiled |\n| `{{file.date\\|date:\"%A\"}}` | `Sunday` | Date object for when file was last modifiled |\n| `{{file.timestamp}}` | `2030-04-07T07:01:36.037Z` | Value for the `datetime` attribute of `