xing-grunt-revise

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

Usage no npm install needed!

<script type="module">
  import xingGruntRevise from 'https://cdn.skypack.dev/xing-grunt-revise';
</script>

README

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