frs-replace v2.0.1

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
• Node API usage
• CLI usage
• Examples
• Benchmarks

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

CLI usage

FRS-replace <regex> <replacement> [options]

Positionals

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.

Examples

Note: while most of examples is using synchronous API method, in all cases .async is applicable as well.

1. Replace all a occurences with b from given foo.js and returns result / writes result to console

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

2. Replace all a occurences with b from given foo.js and save result to foo_replaced.js

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

3. Replace all a occurences with b from given array of files and save result to foo_replaced.js using default \n as result-joining string

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).

4. Replace all 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.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"

5. Replace all a occurences with b in given content string abcd and save result to foo_replaced.js

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

6. Replace all a occurences with b from piped stream and save it to output file

6.1 CLI

<read-file> | FRS-replace a b > <output-file-path>

7. Replaces all a occurences with b from piped stream and pass it through stdout stream to next command

7.1 CLI

<read-file> | FRS-replace a b | <next-command>

8. Both pipe & options styles can be mixed together, here - getting input from i argument and passing output down the stream to next command

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

input & replacement as strings 1000 iterations x 100 repetitions