Package Exports

grunt-text-replace

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (grunt-text-replace) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

grunt-text-replace

General purpose text replacement for grunt.

Allows you to replace text in files using strings, regexs or functions.

Installation

In your project's grunt.js directory, run:

npm install grunt-text-replace

Then add this line to your project's grunt.js:

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.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 your grunt.initConfig({}). It is a multi-task, 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 minimatch 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 is used if 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.template
string containing regex variables $1, $2, etc
combination of the above
function where the return value will be used as the replacement text.

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 defined or found.

// 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"

Release History

v0.2.0 - 2012/11/21. Added tests, refactored internals, strings now replace globally within a file, updated documentation.
v0.1.0 - 2012/11/12. Initial release.