xing-grunt-revise

v1.0.0-beta

Published

2 years ago

Replaces strings on files by using string or regex patterns loaded from a file

Downloads

0High
0Medium
0Low

hannahhoward

judson

gruntplugin string replace regex

xing-grunt-revise

Replaces strings on files by using string or regex patterns from a file

Getting Started

This plugin requires node >= 0.8.0, Grunt >= 0.4.0 and npm >= 1.4.15 (latest stable is recommended).

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install xing-grunt-revise --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('xing-grunt-revise');

If you're still using grunt v0.3.x it's strongly recommended that you upgrade, but in case you can't please use v0.1.1-1.

Configuration

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

Parameters

files `object`

Defines what files this task will edit. Grunt itself has very powerful abstractions, so it is highly recommended you understand the different ways to specify them. Learn more at Gruntfile Files mapping, some options incude compact format, files object format and files array format.

options `object`

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: ';'
  }]
}

Notes

If the pattern is a string, only the first occurrence will be replaced, as stated on String.prototype.replace.
When using Grunt templates, be aware that some security checks are implemented by LoDash and may alter your content (mainly to avoid XSS). To avoid this, see the advanced example below.

Examples

Multiple files and multiple replacements

'xing-revise': {
  dist: {
    files: {
      'dest/': 'src/**',
      'prod/': ['src/*.js', 'src/*.css'],
    },
    options: {
      replacements: [{
        pattern: /\/(asdf|qwer)\//ig,
        replacement: ''$1''
      }, {
        pattern: ',',
        replacement: ';'
      }]
    }
  }

Simple inline content

'xing-revise': {
  inline: {
    files: {
      'dest/': 'src/**',
    },
    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>'
        }
      ]
    }
  }
}

Using files' expand options

For more details, see Grunt's documentation about dynamic files object.

'xing-revise': {
  dist: {
    files: [{
      expand: true,
      cwd: 'src/',
      src: '**/*',
      dest: 'dist/'
    }],
    options: {
      replacements: [{
        pattern: 'hello',
        replacement: 'howdy'
      }]
    }
  }
}

Advanced inline

Since xing-grunt-revise 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.

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:

src/index.html

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

src/partials/header.html

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

src/partials/footer.html

</body></html>

Gruntfile.js

'use strict';

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

  // These plugins provide necessary tasks.
  grunt.loadNpmTasks('xing-grunt-revise');

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

After executing grunt we get the following:

dist/index.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

1.0.0

Update dependencies
Update README.md
Well deserved bump to 1.0.0 (its been stable for long enough now)

0.2.8

Added log message after file is succesfully created. Contributed by donaldpipowitch
Do not report error if one of the replacements resolves to a folder

0.2.7

External libraries are deprecated on Grunt 0.4.2
- Remove grunt.util._ as it is not really required
- Replace grunt.util.async with async

0.2.6

Update Getting Started section
Fix broken link to Gruntfile's File section (#18)

0.2.5

Fix for #16
Fix for Travis CI config file
Added error handling to finish the task if something did not work as expected instead of just fail silently
Updated dev dependencies to latest stable versions

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 [email protected].

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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

xing-grunt-revise

Getting Started

Configuration

Parameters

files object

options object

options.replacements array

Notes

Examples

Multiple files and multiple replacements

Simple inline content

Using files' expand options

Advanced inline

Contributing

Release History

License

files `object`

options `object`

options.replacements `array`