Replace strings on files by using string or regex patters.
JavaScript
Pull request Compare This branch is 51 commits behind eruizdechavez:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
tasks
test
.gitignore
.npmignore
.travis.yml
Gruntfile.js
LICENSE-MIT
README.md
package.json

README.md

grunt-string-replace Build Status Node Dependencies

Replaces strings on files by using string or regex patterns. Attempts to be a String.prototype.replace adapter task for your grunt project.

Getting Started

To install this grunt plugin on your project simply do: npm install grunt-string-replace

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

grunt.loadNpmTasks('grunt-string-replace');

Documentation

Configuration

Inside your Gruntfile.js file add a section named string-replace. This section specifies the files to edit, destinations, patterns and replacements.

Parameters

files object

This defines what files this task will edit and must follow Gruntfile Files mapping.

options object

This controls how this task operates and should contain key:value pairs, see options below.

Options

replacements array

This option will hold all your pattern/replacement pairs. A pattern/replacement pair should contain key:value pairs containing:

  • pattern string or regex
  • replacement string
options: {
  replacements: [{
    pattern: /\/(asdf|qwer)\//ig,
    replacement: '"$1"'
  }, {
    pattern: ',',
    replacement: ';'
  }]
}
Note

If the pattern is a string, only the first occurrence will be replaced, as stated on String.prototype.replace.

Config Example

'string-replace': {
  dist: {
    files: {
      'path/to/directory/': 'path/to/source/*', // includes files in dir
      'path/to/directory/': 'path/to/source/**', // includes files in dir and subdirs
      'path/to/project-<%= pkg.version %>/': 'path/to/source/**', // variables in destination
      'path/to/directory/': ['path/to/sources/*.js', 'path/to/more/*.js'], // include JS files in two diff dirs
      'path/to/filename.ext': 'path/to/source.ext'
    },
    options: {
      replacements: [{
        pattern: /\/(asdf|qwer)\//ig,
        replacement: ''$1''
      }, {
        pattern: ',',
        replacement: ';'
      }]
    }
  },
  inline: {
    options: {
      replacements: [
        // place files inline example
        {
        	pattern: '<script src='js/async.min.js'></script>',
        	replacement: '<script><%= grunt.file.read('path/to/source/js/async.min.js') %></script>'
      	}
      ]
    },
    files: {...}
  }
}

Advanced Usage

Since grunt-string-replace is basically a wrapper of String.prototype.replace you can also provide a function as a replacement pattern instead of a string or a template. To get more details about how to use a function as replacement pattern I recommend you to read Specifying a function as a parameter.

Example

We will be reading file names from HTML comments and use the paths later to fetch the content and insert it inside a resulting HTML. Assuming the following setup:

dist/index.html

<!-- @import partials/header.html -->
content here
<!-- @import partials/footer.html -->

dist/partials/header.html

<html><head></head><body>

dist/partials/footer.html

</body></html>

Gruntfile.js

'use strict';

module.exports = function (grunt) {
  // Project configuration.
  grunt.initConfig({
    config: {
      dist: 'dist/'
    },
    'string-replace': {
      kit: {
        files: {
          '<%= config.dist %>index-dist.html': '<%= config.dist %>index.html'
        },
        options: {
          replacements: [{
            pattern: /<!-- @import (.*?) -->/ig,
            replacement: function (match, p1, offset, string) {
              return grunt.file.read(grunt.config.get('config.dist') + p1);
            }
          }]
        }
      }
    }
  });

  // These plugins provide necessary tasks.
  grunt.loadNpmTasks('grunt-string-replace');

  // Default task.
  grunt.registerTask('default', ['string-replace']);
};

After executing grunt we get the following:

dist/index-dist.html

<html><head></head><body>
content here
</body></html>

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using grunt.

Release History

0.2.4

  • Asynchronously loop files. Original idea contributed by maxnachlinger
  • Inline replacing example on README.md. Contributed by willfarrell

0.2.3

  • Removed dependency with grunt-lib-contrib due to deprecation of 'options' method in favor of Grunt's 'options' util.
  • Updated grunt-contrib-jshint version in package.json to 0.3.0
  • Updated grunt-contrib-watch version in package.json to 0.3.1
  • Updated grunt version in package.json to 0.4.1
  • Added Node.js v0.10 to Travis CI config file

0.2.2

  • Added support to be used as npm module. Contributed by thanpolas.

0.2.1

  • Updated dependencies for Grunt 0.4.0.

0.2.0

  • Added Support for grunt 0.4.0. This version will not support grunt 0.3.x, if you need to use it then npm install grunt-string-replace@0.1.

0.1.1-1

  • Added Clean task (and dev dependency) to remove test generated file before testing.
  • Added Sublime Text project files and test generated file to npm ignore list.

0.1.1

  • Fix dependency with grunt-lib-contrib.

0.1.0-1

  • Fixed a typo on package.json description.
  • Added a note about string pattern behavior.

0.1.0

  • Initial release.

License

Copyright (c) 2012 Erick Ruiz de Chavez. Licensed under the MIT license.