| 1 |
# falafel |
| 2 |
|
| 3 |
Transform the [ast](http://en.wikipedia.org/wiki/Abstract_syntax_tree) on a |
| 4 |
recursive walk. |
| 5 |
|
| 6 |
[](http://ci.testling.com/substack/node-falafel) |
| 7 |
|
| 8 |
[](https://github.com/substack/node-falafel/actions) |
| 9 |
|
| 10 |
This modules uses [acorn](https://npmjs.org/package/acorn) to create an AST from |
| 11 |
source code. |
| 12 |
|
| 13 |
 |
| 14 |
|
| 15 |
# example |
| 16 |
|
| 17 |
## array.js |
| 18 |
|
| 19 |
Put a function wrapper around all array literals. |
| 20 |
|
| 21 |
``` js |
| 22 |
var falafel = require('falafel'); |
| 23 |
|
| 24 |
var src = '(' + function () { |
| 25 |
var xs = [ 1, 2, [ 3, 4 ] ]; |
| 26 |
var ys = [ 5, 6 ]; |
| 27 |
console.dir([ xs, ys ]); |
| 28 |
} + ')()'; |
| 29 |
|
| 30 |
var output = falafel(src, function (node) { |
| 31 |
if (node.type === 'ArrayExpression') { |
| 32 |
node.update('fn(' + node.source() + ')'); |
| 33 |
} |
| 34 |
}); |
| 35 |
console.log(output); |
| 36 |
``` |
| 37 |
|
| 38 |
output: |
| 39 |
|
| 40 |
``` |
| 41 |
(function () { |
| 42 |
var xs = fn([ 1, 2, fn([ 3, 4 ]) ]); |
| 43 |
var ys = fn([ 5, 6 ]); |
| 44 |
console.dir(fn([ xs, ys ])); |
| 45 |
})() |
| 46 |
``` |
| 47 |
|
| 48 |
# methods |
| 49 |
|
| 50 |
``` js |
| 51 |
var falafel = require('falafel') |
| 52 |
``` |
| 53 |
|
| 54 |
## falafel(src, opts={}, fn) |
| 55 |
|
| 56 |
Transform the string source `src` with the function `fn`, returning a |
| 57 |
string-like transformed output object. |
| 58 |
|
| 59 |
For every node in the ast, `fn(node)` fires. The recursive walk is a |
| 60 |
post-order traversal, so children get called before their parents. |
| 61 |
|
| 62 |
Performing a post-order traversal makes it easier to write nested transforms since |
| 63 |
transforming parents often requires transforming all its children first. |
| 64 |
|
| 65 |
The return value is string-like (it defines `.toString()` and `.inspect()`) so |
| 66 |
that you can call `node.update()` asynchronously after the function has |
| 67 |
returned and still capture the output. |
| 68 |
|
| 69 |
Instead of passing a `src` you can also use `opts.source`. |
| 70 |
|
| 71 |
All of the `opts` will be passed directly to |
| 72 |
[acorn](https://npmjs.org/package/acorn). |
| 73 |
|
| 74 |
## custom parser |
| 75 |
|
| 76 |
You may pass in an instance of acorn to the opts as `opts.parser` to use that |
| 77 |
version instead of the version of acorn packaged with this library. |
| 78 |
|
| 79 |
```js |
| 80 |
var acorn = require('acorn-jsx'); |
| 81 |
|
| 82 |
falafel(src, {parser: acorn, plugins: { jsx: true }}, function(node) { |
| 83 |
// this will parse jsx |
| 84 |
}); |
| 85 |
``` |
| 86 |
|
| 87 |
# nodes |
| 88 |
|
| 89 |
Aside from the regular [acorn](https://npmjs.org/package/acorn) data, you can also call |
| 90 |
some inserted methods on nodes. |
| 91 |
|
| 92 |
Aside from updating the current node, you can also reach into sub-nodes to call |
| 93 |
update functions on children from parent nodes. |
| 94 |
|
| 95 |
## node.source() |
| 96 |
|
| 97 |
Return the source for the given node, including any modifications made to |
| 98 |
children nodes. |
| 99 |
|
| 100 |
## node.update(s) |
| 101 |
|
| 102 |
Transform the source for the present node to the string `s`. |
| 103 |
|
| 104 |
Note that in `'ForStatement'` node types, there is an existing subnode called |
| 105 |
`update`. For those nodes all the properties are copied over onto the |
| 106 |
`node.update()` function. |
| 107 |
|
| 108 |
## node.parent |
| 109 |
|
| 110 |
Reference to the parent element or `null` at the root element. |
| 111 |
|
| 112 |
# install |
| 113 |
|
| 114 |
With [npm](http://npmjs.org) do: |
| 115 |
|
| 116 |
``` |
| 117 |
npm install falafel |
| 118 |
``` |
| 119 |
|
| 120 |
# license |
| 121 |
|
| 122 |
MIT |