Tentative to a simple JavaScript AST modification library
JavaScript
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
test
.editorconfig
.gitignore
.jshintrc
.travis.yml
Gruntfile.js
LICENSE-MIT
README.md
package.json fix(package): update acorn-jsx to version 4.0.0 (#35) May 14, 2017

README.md

AST Query

npm tests dependencies

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:

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.

API

Program

var tree = program( sourceCode, escodegenOptions, acornOptions )

  • sourceCode (String) - The source code to edit.
  • escodegenOptions (Object) optional - escodegen option object
  • acornOptions (Object) optional - acorn option object

Returns an AST tree you can then query as explained below:

tree.var( name )

  • 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.

tree.callExpression( name )

  • 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.

tree.assignment( assignedTo )

  • 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
};

tree.body

Property representing the program body in a Body node.

tree.verbatim( body )

  • body (String) - The source code to inline verbatim

Adds body and return a token assigment.

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

Variable node

.value( value )

  • value (String) optionnal - A string containing the new variable value.

It returns the current or new value wrapped in AST query interface.

.rename( name )

  • name (String) - Change the variable name

CallExpression node

.filter( iterator )

  • 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.

.arguments

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

AssignmentExpression node

.value( value )

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.

.value( value )

Get or update the value.

FunctionExpression node

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

.body

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

ObjectExpression node

.key( name )

  • name (String) - Key name Get a key value object or create a blank placeholder

value( value )

Replace current node with a new value. Returns the new value wrapped.

ArrayExpression node

.push( value )

  • value (String) - value to push in the array

.unshift( value )

  • value (String) - value to unshift in the array

.at( index )

  • index (Number) - Index of the value to fetch

Returns a value wrapped in an AST query interface.

value( value )

Replace current node with a new value. Returns the new value wrapped.

Body node

.prepend( code )

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

.append( code )

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 wipbranch.

License

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