Replace text in files using strings, regexs or functions.
npm install grunt-text-replace[travis_image_url]: https://api.travis-ci.org/yoniholmes/grunt-text-replace.png
[travis_page_url]: https://travis-ci.org/yoniholmes/grunt-text-replace
Replace text in files using strings, regexs or functions.
``bash`
npm install grunt-text-replace --save-dev
Then add this line to your project's [gruntfile][getting_started]:
`javascript`
grunt.loadNpmTasks('grunt-text-replace');
[grunt]: http://gruntjs.com/
[getting_started]: https://github.com/gruntjs/grunt/wiki/Getting-started#the-gruntfile
`javascript`
replace: {
example: {
src: ['text/*.txt'], // source files array (supports minimatch)
dest: 'build/text/', // destination directory or file
replacements: [{
from: 'Red', // string replacement
to: 'Blue'
}, {
from: /(f|F)(o{2,100})/g, // regex replacement ('Fooo' to 'Mooo')
to: 'M$2'
}, {
from: 'Foo',
to: function (matchedWord) { // callback replacement
return matchedWord + ' Bar';
}
}]
}
}
Here's another example using [grunt.template][grunt.template], and overwriting
original source files:
`javascript`
replace: {
another_example: {
src: ['build/*.html'],
overwrite: true, // overwrite matched source files
replacements: [{
from: /[0-9]{1,2}\/[0-9]{1,2}\/[0-9]{2,4}/g,
to: "<%= grunt.template.today('dd/mm/yyyy') %>"
}]
}
}
replace is the top level task that goes in your grunt.initConfig({}). It is
a [multi-task][multitask], meaning that it must contain targets, which you can
name anything you like.
[multitask]: https://github.com/gruntjs/grunt/wiki/Configuring-tasks#task-configuration-and-targets
src is an array of source files to be replaced, and is required.
It supports [minimatch][minimatch] paths.
[minimatch]: https://github.com/isaacs/minimatch
dest is the destination for files to be replaced, and can refer to either a:
- file: 'path/output.txt'
- directory:
grunt-text-replace will throw an error if multiple source files are mapped to
a single file.
overwrite should be used for in-place replacement, that is when all you need
to do is overwrite existing files.
To use it, omit dest, otherwise
grunt-text-replace will throw an error. You can only use one or the other.
replacements is an array of from and to replacements. See the
examples above.
from is the old text that you'd like replace. It can be a:
- plain string: 'Red' matches all instances of 'Red' in file/Red/g
- regular expression object: same as above
to is the replacement. It can be a:
- plain string
- string containing a [grunt.template][grunt.template]
- string containing regex variables $1, $2, etc
- combination of the above
- function where the return value will be used as the replacement text (supports
[grunt.template][grunt.template])
- any JavaScript object
#### function
Where to is a function, the function receives 4 parameters:
1. matchedWord: the matched word
2. index: an integer representing point where word was found in a text
3. fullText: the full original text
4. regexMatches: an array containing all regex matches, empty if none
defined or found.
`javascript
// Where the original source file text is: "Hello world"
replacements: [{
from: /wor(ld)/g,
to: function (matchedWord, index, fullText, regexMatches) {
// matchedWord: "world"
// index: 6
// fullText: "Hello world"
// regexMatches: ["ld"]
return 'planet'; //
}
}]
// The new text will now be: "Hello planet"
`
#### JavaScript object
Where to is a JavaScript object, type coercion will apply as follows:
1. null: will result in an empty string
2. undefined: will return in an empty string
3. other: all other values will use default JavaScript type coercion. Examples:
- false: 'false'
- true: 'true'
- 0: '0'
options is an object, specific to a target, and the only supported option is
processTemplates
#### processTemplates
processTemplates when set to false (by default it is true) switches off
grunt.template processing within function return statements. It doesn't work for
string replacements (ie. when the replacement is a string, not a function), as
grunt processes templates within config string values before they are passed to
the plugin.
`javascript``
replace: {
prevent_templates_example: {
src: ['text/*.txt'],
dest: 'build/text/',
options: {
processTemplates: false
},
replacements: [{
from: /url\(.*\)/g,
to: function () {
return "url(<% Don't process this template, retain the delimeters %>)";
}
}]
}
}
[grunt.template]: http://gruntjs.com/api/grunt.template
- Consolidate function parameters. This would mean replacing the 4 existing
function parameters 'matchedWord', 'index', 'fullText' and 'regexMatches' with a single
'data' object with 4 members.
- Source/Destination paths in function callback. The above change makes it easier to
add the source and destination paths as part of the data parameter in the function callback,
which is a requested feature.
- Grunt 4.0 'files' and 'options'. At some point I might move to bringing the plugin
in alignment with the Grunt 4.0 convention of having standard 'files' and 'options' objects.
Patch releases will generally remain undocumented in this release history.
I'll do so if there's enough reason for it, such as a functionality tweak, or
significant bug fix. For more detail see the source.