grunt-transform v0.0.2

grunt-transform

The grunt task to walk the syntax tree, and apply the transformation whenever necessary

Based on Espree (an actively-maintained fork of Esprima) API and used the same AST

Getting Started

This plugin requires Grunt ~0.4.5

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-transform --save-dev

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

grunt.loadNpmTasks('grunt-transform');

grunt-transform task

Run this task with the grunt transform command.

Task targets, files and options may be specified according to the grunt Configuring tasks guide.

Options

tree

Type: Object Default: {range: true}

A complete list of available options:

For more details see the Esprima documentation

features

Type: Object Default: {blockBindings: true}

A complete list of available ECMAScript 6 features:

For more details see the Espree documentation

process

Type: Function (traverse, source) Default: (traverse, source) => source;

This option as an advanced way to control the file contents that are created.

A complete list of available arguments:

Depth-first traversal types

Pre-order type:

1. Display the data part of root element (or current element)
2. Traverse the left subtree by recursively calling the pre-order function.
3. Traverse the right subtree by recursively calling the pre-order function.

Post-order type:

1. Traverse the left subtree by recursively calling the post-order function.
2. Traverse the right subtree by recursively calling the post-order function.
3. Display the data part of root element (or current element).

The trace of a traversal is called a sequentialisation of the tree. The traversal trace is a list of each visited root node. No one sequentialisation according to pre-, in- or post-order describes the underlying tree uniquely. Given a tree with distinct elements, either pre-order or post-order paired with in-order is sufficient to describe the tree uniquely.

For more details see the ast-traverse documentation

Usage Example

var Alter = require('string-alter');

module.exports = function (grunt) {
	grunt.config.init({
		transform: {
			test: {
				options: {
					tree: {
						loc: true
					},

					process: function (traverse, source) {
						var alter = new Alter(source);

						traverse.pre(function (node) {
							if (node.type === 'FunctionDeclaration') {
								var where = JSON.stringify(node.loc, null, '\t');

								alter.wrap(
									node.range[0],
									node.range[1],
									'try {',
									'} catch (error) { console.log("FD:",' + where + ') }'
								);
							}
						});

						return alter.apply();
					}
				},

				files: {
					'cache/actual.js': [ 'tests/fixtures/**/*.js' ]
				}
			}
		},
	});

	grunt.loadNpmTasks('grunt-transform');
	grunt.registerTask('default', ['transform']);
};

Input

function foo () {
	return 1;
}

Output

try {
	function foo () {
		return 1;
	}
}
catch (error) {
	console.log("FD:",{
		"start": {
			"line": 13,
			"column": 0
		},
		"end": {
			"line": 15,
			"column": 1
		}
	);
}

A list of popular ast transformers

falafel burrito string-alter

Tests

grunt test

License

MIT

Links

Esprima online parser Esprima documentation Espree Depth-first search Tree traversal

Task submitted by Alexander Abashkin