AST-query

by SBoudrias

SBoudrias / AST-query

Tentative to a simple JavaScript AST modification library

208 Stars 26 Forks Last release: over 4 years ago (v2.0.0) MIT License 108 Commits 15 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

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
wip
branch.

License

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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.