bomsy / grunt-regex-replace

Grunt plugin to search and replace text content of files based on regular expression patterns

grunt-regex-replace

Grunt plugin to search and replace text content of files based on regular expression patterns

Getting Started

Install this grunt plugin next to your project's grunt.js gruntfile with:

npm install --save-dev grunt-regex-replace

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

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

How to use

Here is a sample of the definition within the object passed to grunt.initConfig

Sample Code

"regex-replace": {
    foofoo: { //specify a target with any name
        src: ['foo/bar.js'],
        actions: [
            {
                name: 'bar',
                search: '(^|\\s)console.log',
                replace: '//console.log',
                flags: 'g'
            },{
                name: 'foo',
                search: 'var v = \'[^\']*\';',
                replace: 'var v = \'<%= pkg.release.version_code %>\';',
                flags: ''
            },{
               name: 'foobar',
               search: new RegExp('\\w+'),
               replace: function() {
                    return 'foofoo';
               }
            },{
               name: 'baz',
               use: function(data) {
                 return data.sourceContent.length > 3;
               },
               search: 'abc',
               replace: 'abcde'
            }
        ]
    }
}

src property

Takes the path to the files relative to the grunt file, it accepts strings as well as an array of file paths. Also supports templates, e.g

src: 'customisation/*.js',
src: '**/*.js',
src: ['foo/bar.js','foo/foo.js'],
src: ['<%= pkg.id %>/bar.js', 'foo/foo.js']

dest property

Takes a file path string or an array of file paths that match the src paths. If a dest file is specified for the corresponding src file, the src file remains unchanged and the changes are applied to the dest file. e.g

1. bla.js will not be overwritten but foo.js will contain the new changes.

 {
    src: ['bla.js'],
    dest: 'foo.js'
 }

2. bla.js and foo.js will be affected as above. baz.js will be overwritten.

 {
    src: ['bla.js', 'baz.js'],
    dest: ['foo.js']
 }

3. bla.js and foo.js will be affected as above. baz.js will be ignored.

 {
    src: ['bla.js'],
    dest: ['foo.js', 'baz.js']
 }

actions property (array | function)

Accepts an array of objects or a function (which returns an array of objects) representing the actions to take place. Each action contains an optional name property, an optional use property, a search property, a replace property and an optional flags property. Here are some examples of the object.

{
    name: 'foo',
    use: function(data) {
      return data.file.indexOf('.skip') === -1 && data.sourceContent.indexOf('console.log') > -1;
    }, //also accepts a template string or any value
    search: '(^|\\s)console.log',
    replace: '//console.log',
    flags: 'gi'
}

{
    name: 'bar',
    search: /\\w+/g, //also accepts new RegExp()
    replace: function() {
        return 'foo';
    }
}

name property

A string value.

use property (function | template string | value)

Default: true

Used to determine whether the corresponding action should be executed or not. If set to true the action executes, if false it does not. Can also be a function which returns a value, a template string producing a value. It enables specifying the conditions for when actions are used.

An object with the following fields is passed in test function:

• file - path to a file that is being processed;
• sourceContent - source contents of the processed file;
• updatedContent - contents of the file after previously applied actions;
• action - object that is representing options of the current action;
• task - reference to the corresponding task;
• grunt - reference to grunt.

search property (regexp | substr)

A regular expression string or object defining the text content to be found.

replace property (substr | function)

A string / regular expression pattern or function to replace the text content. For the replace function, values that match the parenthesized substring matches are passed as arguments

{
    search: new RegExp(/(\w+)\s(\w+)/),
    replace: function(arg1, arg2, ... argN) {
      // arg1 is the full string matched
      // arg2 is the first parenthesized substring match
      // argN is the Nth parenthesized substring match
    }
}

See MDN Documentation for details on "using parenthesized substring matches."

flags property

Regular expressions options (ie gmi). If the flags property is not defined, and the search property is a string, it defaults to 'g'. To specify no options, set the flags to empty string (ie flags : ''). Note: Do not use the flags property if a regexp was used for the search property. Instead, use the flag(s) in your regex. ie: /^[a-z0-9_-]{6,18}$/g

debug log

specify --verbose as a command-line option to show detailed logs

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

• v0.4.0 - added support for dest property
• v0.3.0 - added new use property to actions, removed peerDependencies restrictions
• v0.2.10 - add verbose logging
• v0.2.9 - Clarification for regex flags usage
• v0.2.7 - Support for passing a function to the action property, Updated documentation for using parenthesized substring matches
• v0.2.6 - Support for file globbing patterns.
• v0.2.5 - fix /bin not exist error
• v0.2.4 - added name property, search property now supports regexp object, replace property now supports functions.
• v0.2.3 - task format fixes for compatibilty with 0.4.0.
• v0.2.2 - version fixes
• v0.2.1 - Updated to support grunt 0.4.x
• v0.1.2 - Changes to readme
• v0.1.1 -
• v0.1.0 - First Release

License

Copyright (c) 2012 Hubert Boma Manilla
Licensed under the MIT license.

grunt-regex-replace's Issues

Cannot read property 'src' of undefined

This is my first attempt to use a grunt plugin, so please forgive me if I am missing something obvious -- but I think I'm following the directions from Grunt and from you, and running into an error. My package.json looks like this:

{
  "name": "brink-prototype",
  "version": "0.0.0",
  "dependencies": {
    "bower": "~0.8.6",
    "grunt": "~0.4.1",
    "grunt-regex-replace": "~0.2.2"
  }
}

And my Gruntfile.js looks like this:

module.exports = function(grunt) {
  grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
    'regex-replace': {
      src: ['components/bootstrap/less/navbar.less'],
      actions: [
        {
          search: '\.box-shadow(.*);$',
          replace: '',
          flags: ''
        }
      ]
    }
  });
  grunt.loadNpmTasks('grunt-regex-replace');
  grunt.registerTask('default', ['regex-replace']);
};

Now, when I run grunt from the command line I get the following error:

Running "regex-replace:src" (regex-replace) task
Warning: Cannot read property 'src' of undefined Use --force to continue.
Aborted due to warnings.

Do you have any idea what I'm doing wrong? Thanks so much for your help.

Grunt 0.4 Release

I'm posting this issue to let you know that we will be publishing Grunt 0.4 on Monday, February 18th.

If your plugin is not already Grunt 0.4 compatible, would you please consider updating it? For an overview of what's changed, please see our migration guide.

If you'd like to develop against the final version of Grunt before Monday, please specify "grunt": "0.4.0rc8" as a devDependency in your project. After Monday's release, you'll be able to use "grunt": "~0.4.0" to actually publish your plugin. If you depend on any plugins from the grunt-contrib series, please see our list of release candidates for compatible versions. All of these will be updated to final status when Grunt 0.4 is published.

Also, in an effort to reduce duplication of effort and fragmentation in the developer community, could you review the grunt-contrib series of plugins to see if any of your functionality overlaps significantly with them? Grunt-contrib is community maintained with 40+ contributors—we'd love to discuss any additions you'd like to make.

Finally, we're working on a new task format that doesn't depend on Grunt: it's called node-task. Once this is complete, there will be one more conversion, and then we'll never ask you to upgrade your plugins to support our changes again. Until that happens, thanks for bearing with us!

If you have any questions about how to proceed, please respond here, or join us in #grunt on irc.freenode.net.

Thanks, we really appreciate your work!

A small typo in README

There is a small typo in README.md:

Example af an object.

Add option for each way to keep matching the search expression in a file and action each found

Add option for each way to keep matching the search expression in a file and action each found.

Maybe I am overlooking some usage that will replace all matches in a file, including multiple matches on a single line.

But it seems to only replace the first match, then reset the file back to start,

Add an option to suppress logging

At the moment this plugin generates a lot of logging, two lines for each file. This generates many pages of logging which obscures our more important stuff. Is it possible to suppress this?

If not, is this an interesting feature to add?

Support for this.data.actions to be a function that returns an array

Support for this.data.actions to be a function that returns an array, as well as a raw array.

https://github.com/bomsy/grunt-regex-replace/blob/master/tasks/regex-replace.js#L19

Allowing:

        // This will ensure the first 25 LINK element have closing /> form
        "regex-replace": {
            fixXhtmlLinkElements: {
                src: [ '**/*.html' ],
                actions: function() {
                    var func = function(s) {
                        if(arguments.length > 2) {
                            var l = arguments[1].length;    // length of match0
                            var ch = '';
                            if(l > 0)
                                ch = arguments[1].charAt(l - 1);    // get last char
                            var insert = (ch === '/') ? '' : '/';   // decide if we need to insert '/' or not
                            return arguments[1] + insert + arguments[2];
                        } else {
                            return arguments[0];
                        }
                    };

                    var ary = [];
                    for(var i = 1; i <= 25; i++) {
                        var o = {
                            name: 'link' + i,
                            search: new RegExp('(<link\\s+[^>]*)(>)'),
                            replace: func,
                            flags: 'gi'
                        };
                        ary.push(o);
                    }
                    return ary;
                }
            }
        },

Isn't \s recognized?

Hello:
My example:the test to be replaced

#version           2013-10-14

The following works:

replaceManifestVer: {
                src: ['<%= pkg.targetFolder %>/<%= pkg.help_release %>/help.manifest'],
                actions: [
                    {
                        name: 'update manifest ver',
                        search: '#version.+\-',
                        replace: '',
                        flags: 'g'
                    }
                ]
            }

The txt will leave '14', but the following doesn't work.

{
                        name: 'update manifest ver',
                        search: '#version\s+\-',
                        replace: '',
                        flags: 'g'
                    }

So \s can't be recognized. Why?

Allow RegExp objects as search and callback Function as replace

Currently the task only accepts string arguments.

This is ok for simple expressions but for larger ones the escaping gets tedious:

search: '}\\);\\s*(\\/\\/@\\s*sourceMappingURL=[\\w-\\.]+.js.map\\s*)?$'

Since grunt is javascript anyway it might be cool to support passing-in RegExp objects as search.

Also it could be good to allow replace to be a function just like original String.replace. You could add additional arguments with the name of the action and it's value for extra dynamics.

Provide a destination instead of overwriting original?

Any chance a destination can be added so it doesn't overwrite the original file it is modifying?

options (gmi) are never applied

It looks like the options flags are never applied as part of the replace

Improve documentation for the replace is a function use case

The argument to the replace function use case are:

argument[0] is the full string matched
argument[1] is the first parenthesized substring match
argument[2] is the second parenthesized substring match
argument[3] is the Nth parenthesized substring match ...

see https://developer.mozilla.org/en/docs/Web/JavaScript/Guide/Regular_Expressions and the section "Using parenthesized substring matches"

Grunt 1.0.x support

Right know if one install grunt-regex-replace with grunt 1.0.1 get an error:
The package [email protected] does not satisfy its siblings' peerDependencies requirements!

This is caused by the strict requirement for grunt 0.4.0 specified in https://github.com/bomsy/grunt-regex-replace/blob/master/package.json