Replace text in files using strings, regexs or functions.
Then add this line to your project's gruntfilegettingstarted:
Here's another example using grunt.templategrunt.template, and overwriting original source files:
grunt-text-replace will throw an error if multiple source files are mapped to a single file.
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.
Installation
In your project's gruntfilegettingstarted directory, run:npm install grunt-text-replace --save-dev
Then add this line to your project's gruntfilegettingstarted:
grunt.loadNpmTasks('grunt-text-replace');
Usage
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.templategrunt.template, and overwriting original source files:
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') %>"
}]
}
}
API reference
replace
replace is the top level task that goes in yourgrunt.initConfig({})
. It is
a multi-taskmultitask, meaning that it must contain targets, which you can
name anything you like.src
src is an array of source files to be replaced, and is required. It supports minimatchminimatch paths.dest
dest is the destination for files to be replaced, and can refer to either a:- file:
'path/output.txt'
- directory:
'path/'
grunt-text-replace will throw an error if multiple source files are mapped to a single file.
overwrite
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
replacements is an array of from and to replacements. See the examples above.from
from is the old text that you'd like replace. It can be a:- plain string:
'Red'
matches all instances of 'Red' in file - regular expression object:
/Red/g
same as above
to
to is the replacement. It can be a:- plain string
- string containing a grunt.templategrunt.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
- any JavaScript object
function
Where to is a function, the function receives 4 parameters:- matchedWord: the matched word
- index: an integer representing point where word was found in a text
- fullText: the full original text
- regexMatches: an array containing all regex matches, empty if none
// 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:- null: will result in an empty string
- undefined: will return in an empty string
- other: all other values will use default JavaScript type coercion. Examples:
- false: 'false'
- true: 'true'
- 0: '0'
options
options is an object, specific to a target, and the only supported option is processTemplatesprocessTemplates
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.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 %>)";
}
}]
}
}
Road map
Some changes I'm considering. Happy to receive suggestions for/against:- Consolidate function parameters. This would mean replacing the 4 existing
- Source/Destination paths in function callback. The above change makes it easier to
- Grunt 4.0 'files' and 'options'. At some point I might move to bringing the plugin
Release History
- v0.4.0 - 2014/11/23. Dropping Node 0.8 support. Rewrote internals to prevent grunt-text-replace from make file changes where none are required. This was causing people difficulty with watch tasks.
- v0.3.12 - 2014/06/03. Minor update to docs - fix to a broken link.
- v0.3.11 - 2014/02/09. Added support for non-string or function 'to' replacements.
- v0.3.10 - 2013/12/02. Removed test for no source files found, accepting a pull request to do so. It's quite reasonable that you'd specify rewrite rules for files that may, or may not exist. Let me know if removing this is a problem for you.
- v0.3.9 - 2013/10/26. Copy amends in docs
- v0.3.8 - 2013/09/22. Minor data checking issue, merged from pull request.
- v0.3.7 - 2013/08/26. Bumped grunt requirements from 0.4.0 to 0.4.1 due to changes to path API.
- v0.3.6 - 2013/06/21. Updated links in docs, some of which were pointing to 404 pages.
- v0.3.5 - 2013/06/19. Minor clean up of docs & package.json. No functional changes since 0.3.1.
- v0.3.1 - 2013/02/18. Minor feature addition: processTemplates: false to switch off grunt templates in function return statements.
- v0.3.0 - 2013/02/17. Updated to work in Grunt 4.0. This release is not backwards compatible with grunt 0.3.x.
- v0.2.10 - 2012/12/21. Minor internal refactor to better support globally installed instances of grunt on some systems.
- v0.2.9 - 2012/11/26. Fixed issue where overwrite: true was not working where multiple src files were defined.
- v0.2.7 - 2012/11/25. Fixed issue where replacing a string globally would fail
- v0.2.5 - 2012/11/23. Function replacements now support grunt.template.
- v0.2.0 - 2012/11/21. Added tests, refactored internals, strings now replace
- v0.1.0 - 2012/11/12. Initial release.
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.