README.md

Esrecurse

Esrecurse (esrecurse) is ECMAScript recursive traversing functionality.

Example Usage

The following code will output all variables declared at the root of a file.

esrecurse.visit(ast, {
    XXXStatement: function (node) {
        this.visit(node.left);
        // do something...
        this.visit(node.right);
    }
});

We can use Visitor instance.

var visitor = new esrecurse.Visitor({
    XXXStatement: function (node) {
        this.visit(node.left);
        // do something...
        this.visit(node.right);
    }
});

visitor.visit(ast);

We can inherit Visitor instance easily.

class Derived extends esrecurse.Visitor {
    constructor()
    {
        super(null);
    }

    XXXStatement(node) {
    }
}

function DerivedVisitor() {
    esrecurse.Visitor.call(/* this for constructor */  this  /* visitor object automatically becomes this. */);
}
util.inherits(DerivedVisitor, esrecurse.Visitor);
DerivedVisitor.prototype.XXXStatement = function (node) {
    this.visit(node.left);
    // do something...
    this.visit(node.right);
};

And you can invoke default visiting operation inside custom visit operation.

function DerivedVisitor() {
    esrecurse.Visitor.call(/* this for constructor */  this  /* visitor object automatically becomes this. */);
}
util.inherits(DerivedVisitor, esrecurse.Visitor);
DerivedVisitor.prototype.XXXStatement = function (node) {
    // do something...
    this.visitChildren(node);
};

The childVisitorKeys option does customize the behaviour of this.visitChildren(node). We can use user-defined node types.

// This tree contains a user-defined `TestExpression` node.
var tree = {
    type: 'TestExpression',

    // This 'argument' is the property containing the other **node**.
    argument: {
        type: 'Literal',
        value: 20
    },

    // This 'extended' is the property not containing the other **node**.
    extended: true
};
esrecurse.visit(
    ast,
    {
        Literal: function (node) {
            // do something...
        }
    },
    {
        // Extending the existing traversing rules.
        childVisitorKeys: {
            // TargetNodeName: [ 'keys', 'containing', 'the', 'other', '**node**' ]
            TestExpression: ['argument']
        }
    }
);

We can use the fallback option as well. If the fallback option is "iteration", esrecurse would visit all enumerable properties of unknown nodes. Please note circular references cause the stack overflow. AST might have circular references in additional properties for some purpose (e.g. node.parent).

esrecurse.visit(
    ast,
    {
        Literal: function (node) {
            // do something...
        }
    },
    {
        fallback: 'iteration'
    }
);

If the fallback option is a function, esrecurse calls this function to determine the enumerable properties of unknown nodes. Please note circular references cause the stack overflow. AST might have circular references in additional properties for some purpose (e.g. node.parent).

esrecurse.visit(
    ast,
    {
        Literal: function (node) {
            // do something...
        }
    },
    {
        fallback: function (node) {
            return Object.keys(node).filter(function(key) {
                return key !== 'argument'
            });
        }
    }
);

License

See LICENSE.md.