• Stars
    star
    242
  • Rank 167,048 (Top 4 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created over 11 years ago
  • Updated about 3 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Tentative to a simple JavaScript AST modification library

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.

More Repositories

1

Inquirer.js

A collection of common interactive command line user interfaces.
TypeScript
19,956
star
2

mem-fs-editor

File edition helpers working on top of mem-fs (https://github.com/SBoudrias/mem-fs)
TypeScript
415
star
3

gulp-istanbul

Istanbul unit test coverage plugin for gulp.
JavaScript
185
star
4

mem-fs

Simple in-memory vinyl file store.
TypeScript
123
star
5

class-extend

Backbone like `Class.extend` for Node.js
JavaScript
88
star
6

grouped-queue

In memory queue system prioritizing tasks
JavaScript
86
star
7

gruntfile-editor

An API to modify a Gruntfile.js content
JavaScript
40
star
8

readline2

Node.js Readline façade fixing bugs and issues in v0.8 and v0.10
JavaScript
27
star
9

gulp-exclude-gitignore

Gulp plugin to exclude file contained in .gitignore from the stream
JavaScript
27
star
10

run-async

Utility method to run function either synchronously or asynchronously using the common `this.async()` style.
JavaScript
23
star
11

require.replace

Require.js plugin to load conditionnal modules (i18n and such)
JavaScript
21
star
12

generator-jest

Add jest support to any projects
JavaScript
19
star
13

file-utils

Grunt.file utility fork to add some goodness
JavaScript
16
star
14

inquirer-npm-name

Helper function using inquirer to validate a value provided in a prompt does not exist as an npm package.
JavaScript
13
star
15

detect-conflict

Small utility library that check if a new file content can be merged safely in the on-disk existing file.
JavaScript
11
star
16

gulp-validate-jsdoc

Ensure your JsDoc covers every functions parameters.
JavaScript
7
star
17

dotfiles

My OS X dotfiles (based on necolas/dotfiles)
Shell
7
star
18

instagram-feed-slideshow

Fetch an instagram hash tag feed and displays it in a slideshow
JavaScript
4
star
19

frontend-windows-installer

Installer for most common Frontend/JavaScript work/build tools
3
star
20

Detect-Mobile-Device

PHP based mobile redirection code
2
star
21

flight-filedrop

File dropzone component (FileReader API)
JavaScript
2
star
22

bug-next-head

Demo project of a next.js bug with the Head component
JavaScript
1
star
23

generator-py-microlib

Generate python micro library boilerplate
JavaScript
1
star
24

jquery.3dish-slider

3D "ish" slider plugin for jQuery - Work in progress
JavaScript
1
star