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