1 # falafel
3 Transform the [ast](http://en.wikipedia.org/wiki/Abstract_syntax_tree) on a
4 recursive walk.
6 [![browser support](http://ci.testling.com/substack/node-falafel.png)](http://ci.testling.com/substack/node-falafel)
8 [![build status](https://secure.travis-ci.org/substack/node-falafel.png)](http://travis-ci.org/substack/node-falafel)
10 This modules uses [acorn](https://npmjs.org/package/acorn) to create an AST from
11 source code.
13 ![falafel döner](http://substack.net/images/falafel.png)
15 # example
17 ## array.js
19 Put a function wrapper around all array literals.
21 ``` js
22 var falafel = require('falafel');
24 var src = '(' + function () {
25 var xs = [ 1, 2, [ 3, 4 ] ];
26 var ys = [ 5, 6 ];
27 console.dir([ xs, ys ]);
28 } + ')()';
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 ```
38 output:
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 ```
48 # methods
50 ``` js
51 var falafel = require('falafel')
52 ```
54 ## falafel(src, opts={}, fn)
56 Transform the string source `src` with the function `fn`, returning a
57 string-like transformed output object.
59 For every node in the ast, `fn(node)` fires. The recursive walk is a
60 pre-traversal, so children get called before their parents.
62 Performing a pre-traversal makes it easier to write nested transforms since
63 transforming parents often requires transforming all its children first.
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.
69 Instead of passing a `src` you can also use `opts.source`.
71 All of the `opts` will be passed directly to
72 [acorn](https://npmjs.org/package/acorn).
74 ## custom parser
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.
79 ```js
80 var acorn = require('acorn-jsx');
82 falafel(src, {parser: acorn, plugins: { jsx: true }}, function(node) {
83 // this will parse jsx
84 });
85 ```
87 # nodes
89 Aside from the regular [esprima](http://esprima.org) data, you can also call
90 some inserted methods on nodes.
92 Aside from updating the current node, you can also reach into sub-nodes to call
93 update functions on children from parent nodes.
95 ## node.source()
97 Return the source for the given node, including any modifications made to
98 children nodes.
100 ## node.update(s)
102 Transform the source for the present node to the string `s`.
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.
108 ## node.parent
110 Reference to the parent element or `null` at the root element.
112 # install
114 With [npm](http://npmjs.org) do:
116 ```
117 npm install falafel
118 ```
120 # license
122 MIT