grunt-filetransform

Applies custom functions to transform and concatenate files.

grunt-filetransform

Applies custom functions to transform (map) and concatenate files (reduce).

This plugin requires Grunt ~0.4.1

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 grunt-filetransform --save-dev

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

grunt.loadNpmTasks('grunt-filetransform');

File transform does two things:

  1. It applies a map function to each file.
  2. It takes the result of map functions and merges them with the reduce function.

It's a generic task that you can use to write file transformations without creating a Grunt plugin.

In your project's Gruntfile, add a section named filetransform to the data object passed into grunt.initConfig().

grunt.initConfig({
  filetransform: {
    options: {
      // Task-specific options go here. 
    },
    files: {
      // Files to transform following the Grunt file task configuration rules 
      // you can also override task options for a group of files 
    },
  },
})

The only task specific options are map and reduce:

grunt.initConfig({
  filetransform: {
    options: {
        mapfunction (contents) { return '"' + contents + '"'; },
        reducefunction (results) {
          return results.map(function (f) { return f.contents; }).join('');
        }
    },
    files: {
        'example': ['file1', 'file2']
    },
  },
})

This example will quote the contents of file1 and file2 and them it will join them with a comma. Function arguments are specified bellow.

Any other options besides map and reduce are passed to your function. For instance the previous example can be re-written as:

grunt.initConfig({
  filetransform: {
    options: {
        mapfunction (contentsfilepathoptions) {
          return options.quote + contents + options.quote;
        },
        reducefunction (resultsoptions) {
          return results.map(function (f) { return f.contents; }).join(options.separator);
        },
        quote: '"',
        separator: ','
    },
    files: {
        'example': ['file1', 'file2']
    },
  },
})

The additional options used by your functions can be passed also for each file group, see this project Gruntfile.js for more examples.

  • Type: Function
  • Default value: identity transform
  • Arguments passed to the fuction: (contents, filepath, options)
  • Returns: the data of the transformed source

This function will be invoked for each source file to transform:

  • contents: the source file contents.
  • filepath: the source file path.
  • options: additional options that applies for the src/dest configuration.
  • Type: Function
  • Default value: concatenate all file contents
  • Argumenst passed to the function: (results, options)
  • Returns: the data used to write the destination file

This function is invoked with the results of each options.map call:

  • results: is an array of objects with the following data: {filepath: 'source path', contents: 'map result' }.
  • options: additional options that applies for the src/dest configuration.

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.

  • v0.1.2 - Update of dependency versions.
  • v0.1.0 - First release.