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:

| Option | When set to true | |:----------|:------------------------------------------------ | | range | Nodes have an index-based location range (array) | | loc | Nodes have line and column-based location info | | raw | Literals have extra property which stores the verbatim source | | tokens | An extra array containing all found tokens | | comment | An extra array containing all line and block comments | | tolerant | An extra array containing all errors found, attempts to continue parsing when an error is encountered |

For more details see the Esprima documentation

features

Type: Object Default: {blockBindings: true}

A complete list of available ECMAScript 6 features:

| Feature | When set to true | |:----------------------------------|:------------------------------------------------ | | arrowFunctions | Enable parsing of arrow functions | | blockBindings | Enable parsing of let/const | | destructuring | Enable parsing of destructured arrays and objects | | regexYFlag | Enable parsing of regular expression y flag | | regexUFlag | Enable parsing of regular expression u flag | | templateStrings | Enable parsing of template strings | | binaryLiterals | Enable parsing of binary literals | | octalLiterals | Enable parsing of ES6 octal literals | | unicodeCodePointEscapes | Enable parsing unicode code point escape sequences | | defaultParams | Enable parsing of default parameters | | restParams | Enable parsing of rest parameters | | forOf | Enable parsing of for-of statement | | objectLiteralComputedProperties | Enable parsing computed object literal properties | | objectLiteralShorthandMethods | Enable parsing of shorthand object literal methods | | objectLiteralShorthandProperties | Enable parsing of shorthand object literal properties | | objectLiteralDuplicateProperties | Allow duplicate object literal properties (except 'proto') | | generators | Enable parsing of generators/yield | | spread | Enable parsing spread operator | | classes | Enable parsing classes | | modules | Enable parsing of modules | | jsx | Enable React JSX parsing | | globalReturn | Enable return in global scope |

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:

| Argument | When set to true | |:------------|:-----------------------------------------| | traverse | An object with pre and post visitors | | source | Source code |

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