Neolithic Programming Machine
    Have ideas to improve npm?Join in the discussion! »

    ast-query

    2.0.0 • Public • Published

    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, esprimaOptions )

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

    Install

    npm i ast-query

    DownloadsWeekly Downloads

    56,345

    Version

    2.0.0

    License

    MIT

    Last publish

    Collaborators

    • avatar