Skip to content

Commit dc3ea73

Browse files
adamreisnzadamreisnz
committed
3.0.0
- Drop deprecated API - Drop support for Node 4 and 5 - Refactor and clean up code base - Leverage destructuring - Option to disable globs (#33) - Update readme
1 parent c044c5a commit dc3ea73

16 files changed

+558
-384
lines changed

‎.travis.yml‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
11
language: node_js
22
node_js:
3-
- "4"
4-
- "5"
53
- "6"
64
- "7"
75
- "8"

‎README.md‎

Lines changed: 150 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -17,61 +17,138 @@ npm install replace-in-file
1717
yarn add replace-in-file
1818
```
1919

20-
## Usage
21-
22-
### Specify options
20+
## Basic usage
2321

2422
```js
23+
//Load the library and specify options
2524
const replace = require('replace-in-file');
2625
const options = {
26+
files: 'path/to/file',
27+
from: /foo/g,
28+
to: 'bar',
29+
};
30+
```
31+
32+
### Asynchronous replacement with promises
33+
34+
```js
35+
replace(options)
36+
.then(changes => {
37+
console.log('Modified files:', changes.join(', '));
38+
})
39+
.catch(error => {
40+
console.error('Error occurred:', error);
41+
});
42+
```
43+
44+
### Asynchronous replacement with callback
45+
46+
```js
47+
replace(options, (error, changes) => {
48+
if (error) {
49+
return console.error('Error occurred:', error);
50+
}
51+
console.log('Modified files:', changes.join(', '));
52+
});
53+
```
54+
55+
### Synchronous replacement
56+
57+
```js
58+
try {
59+
const changes = replace.sync(options);
60+
console.log('Modified files:', changes.join(', '));
61+
}
62+
catch (error) {
63+
console.error('Error occurred:', error);
64+
}
65+
```
66+
67+
### Return value
68+
69+
The return value of the library is an array of file names of files that were modified (e.g.
70+
had some of the contents replaced). If no replacements were made, the return array will be empty.
71+
72+
```js
73+
const changes = replace.sync({
74+
files: 'path/to/files/*.html',
75+
from: 'foo',
76+
to: 'bar',
77+
});
2778

28-
//Single file or glob
79+
console.log(changes);
80+
81+
// [
82+
// 'path/to/files/file1.html',
83+
// 'path/to/files/file3.html',
84+
// 'path/to/files/file5.html',
85+
// ]
86+
```
87+
88+
## Advanced usage
89+
90+
### Replace a single file or glob
91+
```js
92+
const options = {
2993
files: 'path/to/file',
94+
};
95+
```
96+
97+
### Replace multiple files or globs
3098

31-
//Multiple files or globs
99+
```js
100+
const options = {
32101
files: [
33102
'path/to/file',
34103
'path/to/other/file',
35104
'path/to/files/*.html',
36105
'another/**/*.path',
37106
],
107+
};
108+
```
38109

39-
//Replacement to make (string or regex)
40-
from: /foo/g,
41-
to: 'bar',
110+
### Replace first occurrence only
42111

43-
//Multiple replacements with the same string (replaced sequentially)
44-
from: [/foo/g, /baz/g],
112+
```js
113+
const options = {
114+
from: 'foo',
45115
to: 'bar',
116+
};
117+
```
46118

47-
//Multiple replacements with different strings (replaced sequentially)
48-
from: [/foo/g, /baz/g],
49-
to: ['bar', 'bax'],
119+
### Replace all occurrences
120+
Please note that the value specified in the `from` parameter is passed straight to the native [String replace method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace). As such, if you pass a string as the `from` parameter, it will _only replace the first occurrence_.
50121

51-
//Specify if empty/invalid file paths are allowed (defaults to false)
52-
//If set to true these paths will fail silently and no error will be thrown.
53-
allowEmptyPaths: false,
122+
To replace multiple occurrences at once, you must use a regular expression for the `from` parameter with the global flag enabled, e.g. `/foo/g`.
54123

55-
//Character encoding for reading/writing files (defaults to utf-8)
56-
encoding: 'utf8',
124+
```js
125+
const options = {
126+
from: /foo/g,
127+
to: 'bar',
128+
};
129+
```
57130

58-
//Single file or glob to ignore
59-
ignore: 'path/to/ignored/file',
131+
### Multiple values with the same replacement
60132

61-
//Multiple files or globs to ignore
62-
ignore: [
63-
'path/to/ignored/file',
64-
'path/to/other/ignored_file',
65-
'path/to/ignored_files/*.html',
66-
'another/**/*.ignore',
67-
]
133+
These will be replaced sequentially.
134+
135+
```js
136+
const options = {
137+
from: [/foo/g, /baz/g],
138+
to: 'bar',
68139
};
69140
```
70141

71-
### Replacing multiple occurrences
72-
Please note that the value specified in the `from` parameter is passed straight to the native [String replace method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace). As such, if you pass a string as the `from` parameter, it will _only replace the first occurrence_.
142+
### Multiple values with different replacements
73143

74-
To replace multiple occurrences at once, you must use a regular expression for the `from` parameter with the global flag enabled, e.g. `/foo/g`.
144+
These will be replaced sequentially.
145+
146+
```js
147+
const options = {
148+
from: [/foo/g, /baz/g],
149+
to: ['bar', 'bax'],
150+
};
151+
```
75152

76153
### Using callbacks for `to`
77154
As the `to` parameter is passed straight to the native [String replace method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace), you can also specify a callback. The following example uses a callback to convert matching strings to lowercase:
@@ -84,81 +161,80 @@ const options = {
84161
};
85162
```
86163

87-
### Asynchronous replacement with promises
164+
### Ignore a single file or glob
88165

89166
```js
90-
replace(options)
91-
.then(changedFiles => {
92-
console.log('Modified files:', changedFiles.join(', '));
93-
})
94-
.catch(error => {
95-
console.error('Error occurred:', error);
96-
});
167+
const options = {
168+
ignore: 'path/to/ignored/file',
169+
};
97170
```
98171

99-
### Asynchronous replacement with callback
172+
### Ignore multiple files or globs
100173

101174
```js
102-
replace(options, (error, changedFiles) => {
103-
if (error) {
104-
return console.error('Error occurred:', error);
105-
}
106-
console.log('Modified files:', changedFiles.join(', '));
107-
});
175+
const options = {
176+
ignore: [
177+
'path/to/ignored/file',
178+
'path/to/other/ignored_file',
179+
'path/to/ignored_files/*.html',
180+
'another/**/*.ignore',
181+
],
182+
};
108183
```
109184

110-
### Synchronous replacement
185+
### Allow empty/invalid paths
186+
If set to true, empty or invalid paths will fail silently and no error will be thrown. For asynchronous replacement only. Defaults to `false`.
111187

112188
```js
113-
try {
114-
const changedFiles = replace.sync(options);
115-
console.log('Modified files:', changedFiles.join(', '));
116-
}
117-
catch (error) {
118-
console.error('Error occurred:', error);
119-
}
189+
const options = {
190+
allowEmptyPaths: true,
191+
};
120192
```
121193

122-
### Return value
194+
### Disable globs
195+
You can disable globs if needed using this flag. Use this when you run into issues with file paths like files like `//SERVER/share/file.txt`. Defaults to `false`.
123196

124-
The return value of the library is an array of file names of files that were modified (e.g.
125-
had some of the contents replaced). If no replacements were made, the return array will be empty.
197+
```js
198+
const options = {
199+
disableGlobs: true,
200+
};
201+
```
126202

127-
For example:
203+
### Specify character encoding
204+
Use a different character encoding for reading/writing files. Defaults to `utf-8`.
128205

129206
```js
130-
const changedFiles = replace.sync({
131-
files: 'path/to/files/*.html',
132-
from: 'a',
133-
to: 'b',
134-
});
135-
136-
// changedFiles could be an array like:
137-
[
138-
'path/to/files/file1.html',
139-
'path/to/files/file3.html',
140-
'path/to/files/file5.html',
141-
]
207+
const options = {
208+
encoding: 'utf8',
209+
};
142210
```
143211

144-
### CLI usage
212+
## CLI usage
145213

146214
```sh
147215
replace-in-file from to some/file.js,some/**/glob.js
216+
[--configFile=replace-config.js]
148217
[--ignore=ignore/files.js,ignore/**/glob.js]
149218
[--encoding=utf-8]
150-
[--allowEmptyPaths]
219+
[--disableGlobs]
151220
[--isRegex]
152221
[--verbose]
153222
```
154223

155-
The flags `allowEmptyPaths`, `ignore` and `encoding` are supported in the CLI.
156-
In addition, the CLI supports the `verbose` flag to list the changed files.
157-
158224
Multiple files or globs can be replaced by providing a comma separated list.
159225

226+
The flags `disableGlobs`, `ignore` and `encoding` are supported in the CLI.
227+
228+
The flag `allowEmptyPaths` is not supported in the CLI as the replacement is
229+
synchronous, and the flag is only relevant for asynchronous replacement.
230+
231+
To list the changed files, use the `verbose` flag.
232+
160233
A regular expression may be used for the `from` parameter by specifying the `--isRegex` flag.
161234

235+
## Version information
236+
From version 3.0.0 onwards, replace in file requires Node 6 or higher. If you need support for Node 4 or 5, use version 2.x.x.
237+
162238
## License
163239
(MIT License)
164240

0 commit comments

Comments
 (0)