|
Jared K. Smith |
2c454d3 |
### Esrecurse [![Build Status](https://travis-ci.org/estools/esrecurse.svg?branch=master)](https://travis-ci.org/estools/esrecurse)
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
Esrecurse ([esrecurse](https://github.com/estools/esrecurse)) is
|
|
Jared K. Smith |
2c454d3 |
[ECMAScript](http://www.ecma-international.org/publications/standards/Ecma-262.htm)
|
|
Jared K. Smith |
2c454d3 |
recursive traversing functionality.
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
### Example Usage
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
The following code will output all variables declared at the root of a file.
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
```javascript
|
|
Jared K. Smith |
2c454d3 |
esrecurse.visit(ast, {
|
|
Jared K. Smith |
2c454d3 |
XXXStatement: function (node) {
|
|
Jared K. Smith |
2c454d3 |
this.visit(node.left);
|
|
Jared K. Smith |
2c454d3 |
// do something...
|
|
Jared K. Smith |
2c454d3 |
this.visit(node.right);
|
|
Jared K. Smith |
2c454d3 |
}
|
|
Jared K. Smith |
2c454d3 |
});
|
|
Jared K. Smith |
2c454d3 |
```
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
We can use `Visitor` instance.
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
```javascript
|
|
Jared K. Smith |
2c454d3 |
var visitor = new esrecurse.Visitor({
|
|
Jared K. Smith |
2c454d3 |
XXXStatement: function (node) {
|
|
Jared K. Smith |
2c454d3 |
this.visit(node.left);
|
|
Jared K. Smith |
2c454d3 |
// do something...
|
|
Jared K. Smith |
2c454d3 |
this.visit(node.right);
|
|
Jared K. Smith |
2c454d3 |
}
|
|
Jared K. Smith |
2c454d3 |
});
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
visitor.visit(ast);
|
|
Jared K. Smith |
2c454d3 |
```
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
We can inherit `Visitor` instance easily.
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
```javascript
|
|
Jared K. Smith |
2c454d3 |
function DerivedVisitor() {
|
|
Jared K. Smith |
2c454d3 |
esrecurse.Visitor.call(/* this for constructor */ this /* visitor object automatically becomes this. */);
|
|
Jared K. Smith |
2c454d3 |
}
|
|
Jared K. Smith |
2c454d3 |
util.inherits(DerivedVisitor, esrecurse.Visitor);
|
|
Jared K. Smith |
2c454d3 |
DerivedVisitor.prototype.XXXStatement = function (node) {
|
|
Jared K. Smith |
2c454d3 |
this.visit(node.left);
|
|
Jared K. Smith |
2c454d3 |
// do something...
|
|
Jared K. Smith |
2c454d3 |
this.visit(node.right);
|
|
Jared K. Smith |
2c454d3 |
};
|
|
Jared K. Smith |
2c454d3 |
```
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
And you can invoke default visiting operation inside custom visit operation.
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
```javascript
|
|
Jared K. Smith |
2c454d3 |
function DerivedVisitor() {
|
|
Jared K. Smith |
2c454d3 |
esrecurse.Visitor.call(/* this for constructor */ this /* visitor object automatically becomes this. */);
|
|
Jared K. Smith |
2c454d3 |
}
|
|
Jared K. Smith |
2c454d3 |
util.inherits(DerivedVisitor, esrecurse.Visitor);
|
|
Jared K. Smith |
2c454d3 |
DerivedVisitor.prototype.XXXStatement = function (node) {
|
|
Jared K. Smith |
2c454d3 |
// do something...
|
|
Jared K. Smith |
2c454d3 |
this.visitChildren(node);
|
|
Jared K. Smith |
2c454d3 |
};
|
|
Jared K. Smith |
2c454d3 |
```
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
The `childVisitorKeys` option does customize the behavoir of `this.visitChildren(node)`.
|
|
Jared K. Smith |
2c454d3 |
We can use user-defined node types.
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
```javascript
|
|
Jared K. Smith |
2c454d3 |
// This tree contains a user-defined `TestExpression` node.
|
|
Jared K. Smith |
2c454d3 |
var tree = {
|
|
Jared K. Smith |
2c454d3 |
type: 'TestExpression',
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
// This 'argument' is the property containing the other **node**.
|
|
Jared K. Smith |
2c454d3 |
argument: {
|
|
Jared K. Smith |
2c454d3 |
type: 'Literal',
|
|
Jared K. Smith |
2c454d3 |
value: 20
|
|
Jared K. Smith |
2c454d3 |
},
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
// This 'extended' is the property not containing the other **node**.
|
|
Jared K. Smith |
2c454d3 |
extended: true
|
|
Jared K. Smith |
2c454d3 |
};
|
|
Jared K. Smith |
2c454d3 |
esrecurse.visit(
|
|
Jared K. Smith |
2c454d3 |
ast,
|
|
Jared K. Smith |
2c454d3 |
{
|
|
Jared K. Smith |
2c454d3 |
Literal: function (node) {
|
|
Jared K. Smith |
2c454d3 |
// do something...
|
|
Jared K. Smith |
2c454d3 |
}
|
|
Jared K. Smith |
2c454d3 |
},
|
|
Jared K. Smith |
2c454d3 |
{
|
|
Jared K. Smith |
2c454d3 |
// Extending the existing traversing rules.
|
|
Jared K. Smith |
2c454d3 |
childVisitorKeys: {
|
|
Jared K. Smith |
2c454d3 |
// TargetNodeName: [ 'keys', 'containing', 'the', 'other', '**node**' ]
|
|
Jared K. Smith |
2c454d3 |
TestExpression: ['argument']
|
|
Jared K. Smith |
2c454d3 |
}
|
|
Jared K. Smith |
2c454d3 |
}
|
|
Jared K. Smith |
2c454d3 |
);
|
|
Jared K. Smith |
2c454d3 |
```
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
We can use the `fallback` option as well.
|
|
Jared K. Smith |
2c454d3 |
If the `fallback` option is `"iteration"`, `esrecurse` would visit all enumerable properties of unknown nodes.
|
|
Jared K. Smith |
2c454d3 |
Please note circular references cause the stack overflow. AST might have circular references in additional properties for some purpose (e.g. `node.parent`).
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
```javascript
|
|
Jared K. Smith |
2c454d3 |
esrecurse.visit(
|
|
Jared K. Smith |
2c454d3 |
ast,
|
|
Jared K. Smith |
2c454d3 |
{
|
|
Jared K. Smith |
2c454d3 |
Literal: function (node) {
|
|
Jared K. Smith |
2c454d3 |
// do something...
|
|
Jared K. Smith |
2c454d3 |
}
|
|
Jared K. Smith |
2c454d3 |
},
|
|
Jared K. Smith |
2c454d3 |
{
|
|
Jared K. Smith |
2c454d3 |
fallback: 'iteration'
|
|
Jared K. Smith |
2c454d3 |
}
|
|
Jared K. Smith |
2c454d3 |
);
|
|
Jared K. Smith |
2c454d3 |
```
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
If the `fallback` option is a function, `esrecurse` calls this function to determine the enumerable properties of unknown nodes.
|
|
Jared K. Smith |
2c454d3 |
Please note circular references cause the stack overflow. AST might have circular references in additional properties for some purpose (e.g. `node.parent`).
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
```javascript
|
|
Jared K. Smith |
2c454d3 |
esrecurse.visit(
|
|
Jared K. Smith |
2c454d3 |
ast,
|
|
Jared K. Smith |
2c454d3 |
{
|
|
Jared K. Smith |
2c454d3 |
Literal: function (node) {
|
|
Jared K. Smith |
2c454d3 |
// do something...
|
|
Jared K. Smith |
2c454d3 |
}
|
|
Jared K. Smith |
2c454d3 |
},
|
|
Jared K. Smith |
2c454d3 |
{
|
|
Jared K. Smith |
2c454d3 |
fallback: function (node) {
|
|
Jared K. Smith |
2c454d3 |
return Object.keys(node).filter(function(key) {
|
|
Jared K. Smith |
2c454d3 |
return key !== 'argument'
|
|
Jared K. Smith |
2c454d3 |
});
|
|
Jared K. Smith |
2c454d3 |
}
|
|
Jared K. Smith |
2c454d3 |
}
|
|
Jared K. Smith |
2c454d3 |
);
|
|
Jared K. Smith |
2c454d3 |
```
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
### License
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
Copyright (C) 2014 [Yusuke Suzuki](https://github.com/Constellation)
|
|
Jared K. Smith |
2c454d3 |
(twitter: [@Constellation](https://twitter.com/Constellation)) and other contributors.
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
Redistribution and use in source and binary forms, with or without
|
|
Jared K. Smith |
2c454d3 |
modification, are permitted provided that the following conditions are met:
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
* Redistributions of source code must retain the above copyright
|
|
Jared K. Smith |
2c454d3 |
notice, this list of conditions and the following disclaimer.
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
* Redistributions in binary form must reproduce the above copyright
|
|
Jared K. Smith |
2c454d3 |
notice, this list of conditions and the following disclaimer in the
|
|
Jared K. Smith |
2c454d3 |
documentation and/or other materials provided with the distribution.
|
|
Jared K. Smith |
2c454d3 |
|
|
Jared K. Smith |
2c454d3 |
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
Jared K. Smith |
2c454d3 |
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
Jared K. Smith |
2c454d3 |
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
Jared K. Smith |
2c454d3 |
ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
|
|
Jared K. Smith |
2c454d3 |
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
|
Jared K. Smith |
2c454d3 |
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
|
Jared K. Smith |
2c454d3 |
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
|
Jared K. Smith |
2c454d3 |
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
Jared K. Smith |
2c454d3 |
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
|
Jared K. Smith |
2c454d3 |
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|