Debian Codegraph @

readme.markdown

raw
1 # falafel
2
3 Transform the [ast](http://en.wikipedia.org/wiki/Abstract_syntax_tree) on a
4 recursive walk.
5
6 [![browser support](http://ci.testling.com/substack/node-falafel.png)](http://ci.testling.com/substack/node-falafel)
7
8 [![build status](https://github.com/substack/node-falafel/workflows/Node%20CI/badge.svg?branch=master)](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 ![falafel döner](./falafel.png)
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