README
FRS-replace
The fastest (see benchmarks) CLI & Node wrapper around javascript replace which allows on-the-fly replacing (with or without changing input files), globbing, piping and many more!
Installation
yarn
yarn add frs-replace
npm
npm install frs-replace
download zipped from FRS-replace Releases
Node API usage
FRS-replace package provides 2 methods for synchronous / asynchronous (with promise and ES6 async
/await
syntax support) usage:
const FRSReplace = require('FRS-replace');
FRSReplace.sync({/* options */})
FRSReplace.async({/* options */})
Where /* options */
is an object containing:
Note: remember that you need to provide some input for FRS-replace to work, so one of the parameters: input or content are required
Option | Type | Default | Description |
---|---|---|---|
input | string or <string>array | undefined | Path/fast-glob pattern to files to read & replace from, if multiple files are specified results are joined with inputJoinString option's value |
inputReadOptions | string or object | utf8 | Options passed to readFileSync when reading input file |
inputGlobOptions | object | undefined | Options passed to fast-glob when resolving glob patterns |
inputJoinString | string | \n | String used when joining multiple files, passed directly to javascript join |
content | string | undefined | Content to be replaced (takes precedence over file input) |
regex | string or RegExp Object | - | Used as a first argument of javascript replace |
replacement | string | - | Passed as a second argument to javascript replace |
output | string | undefined | Path of an output file |
outputWriteOptions | string or object | utf8 | Passed as options argument of write's .sync |
CLI usage
FRS-replace <regex> <replacement> [options]
Positionals
Option | Type | Description |
---|---|---|
<regex> | string | First parameter to RegExp constructor |
<replacement> | string | String or path to replacement function file (see ‑‑replace‑fn switch for details) |
Options
Note: Every boolean option can be negated with use of
--no-
prefix, e.g.--stdout
or--no-stdout
turn stdout output on or off, respectively.
Note: Object types can be set using dot notation. So, e.g. if you want to pass
utf8
value under i-read-opts encoding field you should write--i-read-opts.encoding utf8
.
Option | Type | Default | Description |
---|---|---|---|
‑i, ‑‑input | string or <string>array | - | Files/fast-glob pattern to files to read & replace from |
‑‑i-read-opts | string or object | utf8 | Passed to readFileSync when reading input file |
‑‑i-glob-opts | object | undefined | Passed to fast-glob when resolving glob patterns |
‑‑i-join-str | string | \n | Used when joining multiple files, passed directly to javascript join |
‑o, ‑‑output | string | - | Output file name/path (replaces the file if it already exists and creates any intermediate directories if they don't already exist) |
‑‑o-write-opts | string or object | utf8 | Passed as options argument of write's .sync |
‑f, ‑‑flags | combination of gim flags | g | RegExp flags |
‑c, ‑‑content | string | - | Content to be replaced (takes precedence over stream & file input) |
‑‑stdout | boolean | true if piped input present, false otherwise | Force sending output on stdout |
‑r, ‑‑replace‑fn | boolean | false | Treat replacement argument as path to file containing replacement function |
‑h, ‑‑help | boolean | - | Show help |
‑v, ‑‑version | boolean | - | Show version number |
Examples
Note: while most of examples is using synchronous API method, in all cases
.async
is applicable as well.
a
occurences with b
from given foo.js
and returns result / writes result to console
1. Replace all 1.1 API
const FRSReplace = require('FRS-replace')
/* synchronously */
const resultSync = FRSReplace.sync({
input : 'foo.js',
regex : new RegExp('a', 'g'),
replacement : 'b',
output : 'foo_replaced.js'
})
// work with result here
/* asynchronously */
FRSReplace.async({
input : 'foo.js',
regex : new RegExp('a', 'g'),
replacement : 'b'
})
.then(resultAsync => {
// work with result here */
})
/* asynchronously ES6 syntax (must be runned inside async function) */
const resultAsync = await FRSReplace.async({
input : 'foo.js',
regex : new RegExp('a', 'g'),
replacement : 'b'
})
// work with result here */
1.2 CLI
FRS-replace a b -i foo.js --stdout
a
occurences with b
from given foo.js
and save result to foo_replaced.js
2. Replace all 2.1 API
const result = require('FRS-replace').sync({
input : 'foo.js',
regex : new RegExp('a', 'g'),
replacement : 'b',
output : 'foo_replaced.js'
})
2.2 CLI
FRS-replace a b -i foo.js -o foo_replaced.js
a
occurences with b
from given array of files and save result to foo_replaced.js
using default \n
as result-joining string
3. Replace all 3.1 API
const result = require('FRS-replace').sync({
input : ['foo.js', 'foo2.js'],
regex : new RegExp('a', 'g'),
replacement : 'b',
output : 'foo_replaced.js'
})
3.2 CLI
FRS-replace a b -i foo.js foo2.js -o foo_replaced.js --i-join-str "\n/////\n"
or
FRS-replace a b -i foo.js -i foo2.js -o foo_replaced.js --i-join-str "\n/////\n"
Note: Arrays can be passed under single flag-entry as a space-separated list or under same flag repeated multiple times (all values will be concatenated into single array using, details - yargs array notation).
a
occurences with b
from all .js
files in foo
directory and save result to foo_replaced.js
using \n/////\n
as result-joining string
4. Replace all 4.1 API
const result = require('FRS-replace').sync({
input : 'foo/*.js',
regex : new RegExp('a', 'g'),
replacement : 'b',
inputJoinString : '\n/////\n',
output : 'foo_replaced.js'
})
4.2 CLI
FRS-replace a b -i foo/*.js -o foo_replaced.js --i-join-str "\n/////\n"
a
occurences with b
in given content string abcd
and save result to foo_replaced.js
5. Replace all 5.1 API
const result = require('FRS-replace').sync({
content : 'abcd',
regex : new RegExp('a', 'g'),
replacement : 'b',
output : 'foo_replaced.js'
})
5.2 CLI
FRS-replace a b --content abcd -o foo_replaced.js
a
occurences with b
from piped stream and save it to output file
6. Replace all 6.1 CLI
<read-file> | FRS-replace a b > <output-file-path>
a
occurences with b
from piped stream and pass it through stdout
stream to next command
7. Replaces all 7.1 CLI
<read-file> | FRS-replace a b | <next-command>
i
argument and passing output down the stream to next command
8. Both pipe & options styles can be mixed together, here - getting input from 8.1 CLI
FRS-replace a b -i foo.js | <next-command>
Benchmarks (Node v10.16.0)
input as glob pattern [40 files x 1000 iterations x 100 repetitions]
Library (best bolded) | Execution time [s] | Difference percentage (comparing to best time) |
---|---|---|
FRS-replace async | 0.01764040 | 102.9716% |
FRS-replace sync | 0.00869107 | 0.0000% |
replace-in-file | 0.02243486 | 158.1369% |
replace async | N/A | N/A |
replace sync | 0.05524010 | 535.5961% |
replace-string | N/A | N/A |
input & replacement as strings [1000 iterations x 100 repetitions]
Library (best bolded) | Execution time [s] | Difference percentage (comparing to best time) |
---|---|---|
FRS-replace async | 0.00010628 | 231.1801% |
FRS-replace sync | 0.00003368 | 4.9407% |
replace-in-file | N/A | N/A |
replace async | N/A | N/A |
replace sync | N/A | N/A |
replace-string | 0.00003209 | 0.0000% |