ast-query

AST Query
================

  

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 tree and use conditional structure a lot. AST Query hide these complexities 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.

Getting Started
================

Install: npm install --save ast-query

First, you need to pass a program code into AST query:

`` javascript
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.

` javascript
// ...
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.


API
================

Program
----------------

$3

Find and returns a Variable node.

Given this code

` js
var bar = 23;
`

You'd call tree.var('bar') to get the Variable node.

$3

Find a function or method call and return a CallExpression node

Given this code

`js
grunt.initConfig({});
`

You'd call tree.callExpression('grunt.initConfig') to get the CallExpression node.

$3

Find and return an AssignmentExpression node.

You'd call tree.assignment('module.exports') to query the code below:

`js
module.exports = function () {
// code
};
`


$3

Property representing the program body in a Body node.

$3

`js
tree.body.append('var a = 1;' + tree.verbatim('ANYTHING'));
`

Variable node
-----------------

$3

A property pointing to an ArrayExpression node referencing the called function arguments.

AssignmentExpression node
--------------------

$3

Replace the assignment value with a new value or return the current value wrapped in an AST query interface.

Literal node
--------------------

A Literal node represent a raw JavaScript value as a String, a Number or a Boolean.

$3

Get or update the value.

FunctionExpression node
-------------------

Node representing a function declaration (e.g. function () {}).

$3

Property pointing to a Body node representing the function expression body.

ObjectExpression node
-------------------

$3

Preprend the given code lines in the body. If a "use strict"; statement is present, it always stay first.

$3

Append the given code lines in the body.

Contributing
=====================

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.

License
=====================

Copyright (c) 2013 Simon Boudrias (twitter: @vaxilart)
Licensed under the MIT license.