## A) Setup
Install package for node:
```shell
$ npm install --save-dev replacer-util
```

## B) Usage
### 1. npm package.json scripts
Run `replacer` from the `"scripts"` section of your **package.json** file.

Parameters:
* The **first** parameter is the *source* folder or file.
* The **second** parameter is the *target* folder.

Example **package.json** scripts:
```json
"scripts": {
"build-web": "replacer src/web --ext=.html dist/website",
"poetry": "replacer poems --find=human --replacement=robot dystopian-poems"
},
```
In addition to the `--find` and `--replacement` CLI flags, template outputs in the source files will be replaced with their corresponding template variable values. 
The 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.

### 2. Command-line npx
Example terminal commands:
```shell
$ npm install --save-dev replacer-util
$ npx replacer src/web ext=.html docs/api-manual
```
You can also install **replacer-util** globally (`--global`) and then run it anywhere directly from the terminal.

### 3. CLI flags
Command-line flags:
| Flag | Description | Value |
| ----------------- | ----------------------------------------------------- | ---------- |
| `--cd` | Change working directory before starting search. | **string** |
| `--concat` | Merge all files into one file in the target folder. | **string** |
| `--content` | String to be used instead of the input file contents. | **string** |
| `--exclude` | Skip files containing the string in their path. | **string** |
| `--ext` | Filter files by file extension, such as `.js`.
Use a comma to specify multiple extensions. | **string** |
| `--find` | Text to search for in the source input files. | **string** |
| `--header` | Prepend a line of text to each file. | **string** |
| `--no-liquid` | Turn off LiquidJS templating. | N/A |
| `--no-source-map` | Remove any `sourceMappingURL` comment directives. | N/A |
| `--note` | Place to add a comment only for humans. | **string** |
| `--quiet` | Suppress informational messages. | N/A |
| `--regex` | Pattern to search for in the source input files. | **string** |
| `--rename` | New output filename. | **string** |
| `--replacement` | Text to insert into the target output files. | **string** |
| `--summary` | Only print out the single line summary message. | N/A |

To avoid issues on the command line, problematic characters can be _"escaped"_ with safe strings as listed below.

Escape characters:
| Character | Safe stand-in string |
| --------- | -------------------- |
| `'` | `{{apos}}` |
| `!` | `{{bang}}` |
| `}` | `{{close-curly}}` |
| `=` | `{{equals}}` |
| `>` | `{{gt}}` |
| `<` | `{{lt}}` |
| `{` | `{{open-curly}}` |
| `\|` | `{{pipe}}` |
| `"` | `{{quote}}` |
| `;` | `{{semi}}` |
| ` ` | `{{space}}` |

### 4. Example CLI usage
Examples:
- `replacer src build`

Recursively copies all the files in the **src** folder to the **build** folder using the data in **package.json** to update the template outputs.

- `replacer src/docs --ext=.md --find=Referer --replacement=Referrer output/fixed`

Fixes spelling error in markdown files.

- `replacer src/docs --ext=.md --find=Referer --replacement=Referrer --no-liquid output/fixed`

Same as previous example but disables LiquidJS templating (useful in case source files contain characters inadvertently interpreted at templating commands).

- `replacer web '--find=cat dog' '--replacement= cat{{pipe}}dog ' target`

`replacer web --find=cat\ dog --replacement=\ cat{{pipe}}dog\ target`

`replacer web --find=cat{{space}}dog --replacement={{space}}cat{{pipe}}dog{{space}} target`

Replaces all occurances of the string `'cat dog'` with `' cat|dog '` (note the _3 different_ ways to _"escape"_ a space character).

- `replacer src --ext=.js --no-liquid --concat=bundle.js build`

Merges all JS files into **build/bundle.js**.

- `replacer app/widgets --ext=.less --content=@import{{space}}{{quote}}{{file.dir}}/{{file.name}}{{quote}}{{semi}} --concat=widgets.less app/style`

Creates a single LESS file that imports the LESS files of every widget component.

- `replacer src --summary build`

Displays the summary but not the individual files copied.

- `replacer src --regex=/^--/gm --replacement=🥕🥕🥕 build`

Finds double dashes at the start of lines and replace them with 3 carrots. 
Note the `g` and `m` [regex options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#advanced_searching_with_flags).

- `replacer build/my-app.js --rename=my-app.browser.js build`

Copies **my-app.js** to **my-app.browser.js** without making and changes.

- `replacer src/web --ext=.html --rename=index.html dist/website`

Renames all HTML files, such as **src/web/about/about.html**, to **index.html** while preserving the folder structure.

- `replacer --cd=spec/fixtures source --find=insect --replacement=A.I. target`

Removes all insects. See: [source/mock1.html](spec/fixtures/source/mock1.html) and [target/mock1.html](spec/fixtures/target/mock1.html)

- `replacer node_modules/chart.js/dist/chart.umd.js --no-source-map build/1-pre/libs`

Removes the `//# sourceMappingURL=chart.umd.js.map` line at the bottom of the **Chart.js** distribution file.

For examples of using `replacer` as part of front-end build process, check out the `"runScriptsConfig"` section of:

https://github.com/dna-engine/data-dashboard/blob/main/package.json

_**Note:** Single quotes in commands are normalized so they work cross-platform and avoid the errors often encountered on Microsoft Windows._

### 5. Template outputs and filter formatters
The 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). 
Custom variables are created with the [assign](ttps://liquidjs.com/tags/assign.html) tag.

Three special variables are available by default:
* `file` ([path](https://nodejs.org/api/path.html#pathparsepath) and date information about the source file)
* `package` (values from your project's **package.json** file)
* `webRoot` (relative path to root folder: `.`, `..`, `../..`, `../../..`, etc.)

For example, a TypeScript file with the lines:
```typescript
const msg1: string = 'The current release of {{package.name | upcase}} is v{{package.version}}.';
const msg2: string = 'This file is: {{file.base}}';
```
will be transformed into something like:
```typescript
const msg1: string = 'The current release of MY-COOL-NPM-PACKAGE is v1.2.3.';
const msg2: string = 'This file is: my-app.ts';
```