This project is a tentative to create a simple JavaScript AST modification library.
If you've ever worked with AST trying to edit source code, you'll know it is a bad time. AST syntax is terse and forces you to loop a three and use conditionals structure a lot. AST Query hide this complexity behind a declarative façade.
Making the simplicity choice means AST Query won't try to cover the full AST API. Rather we strive to answer commons needs.
Install: npm install --save ast-query
First, you need to pass a program code into AST query:
var program = require("ast-query");
var tree = program("var a = 'foo'");
This function returns a wrapped AST tree you can query and modify.
Once you've modified the AST, get the source code back by calling the toString
method on the tree.
// ...
tree.var("a").value("'bar'");
console.log( tree.toString() );
// LOG: var a = 'bar';
Remember that you are editing source code. This mean you provide raw source code strings. This mean you need to double wrap strings (e.g.: "'foo'"
). If that's not done, AST-query assume you're referencing a variable called foo
.
- sourceCode (String) - The source code to edit.
Returns an AST tree you can then query as explained below:
- name (String) - The variable name
Find and returns a Variable
node.
Given this code
var bar = 23;
You'd call tree.var('bar')
to get the Variable node.
- name (String) - The name of the function or method being called.
Find a function or method call and return a CallExpression
node
Given this code
grunt.initConfig({});
You'd call tree.callExpression('grunt.initConfig')
to get the CallExpression node.
- assignedTo (String) - The name (name or object) a value is assigned to
Find and return an AssignmentExpression
node.
You'd call tree.assignment('module.exports')
to query the code below:
module.exports = function () {
// code
};
Property representing the program body in a Body
node.
- value (String) optionnal - A string containing the new variable value.
It returns the current or new value wrapped in AST query interface.
- name (String) - Change the variable name
- iterator (Function) - Function receiving each node as arguments and returning true to keep the current node in the returned set.
Return a new CallExpression nodes collection with nodes passing the iterator test.
A property pointing to an ArrayExpression
node referencing the called function arguments.
Replace the assignment value with a new value or return the current value wrapped in an AST query interface.
A Literal node represent a raw JavaScript value as a String, a Number or a Boolean.
Get or update the value.
Node representing a function declaration (e.g. function () {}
).
Property pointing to a Body
node representing the function expression body.
- name (String) - Key name Get a key value object or create a blank placeholder
Replace current node with a new value. Returns the new value wrapped.
- value (String) - value to push in the array
- value (String) - value to unshift in the array
- index (Number) - Index of the value to fetch
Returns a value wrapped in an AST query interface.
Preprend the given code lines in the body. If a "use strict";
statement is present, it always stay first.
Append the given code lines in the body.
Style Guide: Please base yourself on Idiomatic.js
style guide with two space indent
Unit test: Unit test are wrote in Mocha. Please add a unit test for every new feature
or bug fix. npm test
to run the test suite.
Documentation: Add documentation for every API change. Feel free to send corrections
or better docs!
Pull Requests: Send fixes PR on the master
branch. Any new features should be send
on the wip
branch.
Copyright (c) 2013 Simon Boudrias (twitter: @vaxilart)
Licensed under the MIT license.