esprima-ast-utils v0.0.7

esprima-ast-utils

Node module to manipulate, transform, query and debug esprima ASTs.

Objective

When you edit esprima AST and go back to code with escodegen you lose too much information because primary you don't keep track of ranges, tokens, comments etc. esprima-ast-utils do this for you, so no escodegen is needed, you can edit the AST directly and code everything is in sync.

API

io

parse (String:str , Boolean:debug) -> Object

Parse given str

Parameters:

• str

• debug: display $id, $parent and $code in console.log (enumerable=true)

Returns:

• Object

Note: location it's not supported, and won't sync with changes, range/rokens do.

parseWrap (String:str , Boolean:debug) -> Object

Wrap your code into a function and parse given str. Needed if your code contains a ReturnStatement at Program level.

Parameters:

• str

• debug: display $id, $parent and $code in console.log (enumerable=true)

Returns:

• Object

Note: location it's not supported, and won't sync with changes, range/rokens do.

parseFile (String:file , Boolean:debug) -> Object

Parse given file

Parameters:

• file: Path

• debug: display $id, $parent and $code in console.log (enumerable=true)

Returns:

• Object

Note: : NodeJS only

encode (Object:tree) -> String

Return tree.$code, just for API completeness.

Parameters:

• tree

Returns:

• String

walk

traverse (Object:node, Function:callback , Number:depth)

traverse AST

Parameters:

• node

• callback: function(node, parent, property, index, depth) You can return false to stop traverse

• depth: (0) current depth

• recursive: (true) recursively traverse

parentize (Object:root , Boolean:debug)

traverse AST and set $parent node

Parameters:

• root

• debug: display $parent in console.log (enumerable=true)

idze (Object:node , Boolean:debug)

traverse AST and set an unique $id to every node

Parameters:

• node

• debug: display $id in console.log (enumerable=true)

attachComments (Object:root)

Traverse the AST and add comments as nodes, so you can query them. Loop thought comments and find a proper place to inject (BlockStament or alike)

• attach the comment to the before nearest children
• if a children contains the comment it's considered invalid
• push otherwise

Parameters:

• root

filter (Object:node, Function:callback , Function:traverse_fn) -> Array

traverse and filter given AST based on given callback

Parameters:

• node

• callback

• traverse_fn

Returns:

• Array: Every match of the callback

getParent (Object:node, Function:callback) -> Object|NULL

Get parent node based on given callback, stops on true

Parameters:

• node

• callback

Returns:

• Object|NULL

getRoot (Object:node) -> Object

get the root of the AST

Parameters:

• node

Returns:

• Object

clone (Object:node) -> Object

Recursive clone a node. Do no include "$" properties like $parent or $id If you want those, call parentize - idze after cloning

Parameters:

• node

Returns:

• Object

debug

debug_tree (Object:tree , Number:max_width)

Show your tree in various ways to easy debug Big trees will be always a pain, so keep it small if possible

Parameters:

• tree: Any node, if root tokens & source will be displayed

• max_width: max tokens per line

• display_code_in_tree: when display the tree attach the code on the right

query

getFunction (Object:node, String:fn_name) -> Object|NULL

filter the AST and return the function with given name, null otherwise.

Parameters:

• node

• fn_name

Returns:

• Object|NULL

getFunctionBlock (Object:node, String:fn_name) -> Object|NULL

filter the AST and return the function > block with given name, null otherwise.

Parameters:

• node

• fn_name

Returns:

• Object|NULL

isFunctionDeclared (Object:node, String:fn_name) -> Boolean

shortcut

Parameters:

• node

• fn_name

Returns:

• Boolean

hasVarDeclaration (Object:node, String:var_name) -> Boolean

shortcut

Parameters:

• node

• var_name

Returns:

• Boolean

isVarDeclared (Object:node, String:var_name) -> Boolean

reverse from node to root and look for a Variable declaration

Parameters:

• node

• var_name

Returns:

• Boolean

Note: It's not perfect because VariableDeclaration it's not hoisted

contains (Object:node, Object:subnode) -> Boolean

node constains subnode

Parameters:

• node

• subnode

Returns:

• Boolean

hasBody (Object:node) -> Boolean

Has a body property, use to freely attach/detach

Parameters:

• node

Returns:

• Boolean

isComment (Object:node) -> Boolean

shortcut: Is a comment (Line or Block) and has text

Parameters:

• node

Returns:

• Boolean

getComment (Object:node, String:comment) -> Object

shortcut: search for a comment (trim it's content for maximum compatibility)

Parameters:

• node

• comment

Returns:

• Object

getCode (Object:node) -> String

shortcut: Return node code

Parameters:

• node

Returns:

• String

getArgumentList (Object:node) -> Array

Return FunctionDeclaration arguments name as a list

Parameters:

• node

Returns:

• Array

getDefaultProperty (Object:node)

Parameters:

• node

manipulations

attach (Object:node, String:property, Number|NULL:position, String|Object:str)

Attach Code/Program to given node.

Parameters:

• node: node to attach

• property: Where attach, could be an array or an object

• position: index if an array is used as target property

• str: String is preferred if not possible remember that only Program can be attached, you may consider using toProgram

Note: tokens are updated

Note: range is updated

Note: comments are not attached to root.comments (invalid-comments)

attachPunctuator (Object:tree, String:punctuator, Number:position) -> String

Attach a punctuator and keep the tree ranges sane. The Punctuator can be anything... be careful!

Parameters:

• tree

• punctuator

• position

Returns:

• String: detached code string

Note: The Punctuator is not parsed and could be assigned to nearest literal or alike.

detach (Object:node, String:property) -> String

Detach given node from it's parent

Parameters:

• node

• property

Returns:

• String: detached code string

Note: node.$parent is set to null, remember to save it first if you need it.

attachAfter (Object:node, String|Object:str , String:property)

Attach after node, that means node.$parent.type is a BockStament

Parameters:

• node

• str: String is preferred if not possible remember that only Program can be attached, you may consider using toProgram

• property: where to search node in the parent

attachBefore (Object:node, String|Object:str)

Attach before node, that means node.$parent.type is a BockStament

Parameters:

• node

• str: String is preferred if not possible remember that only Program can be attached, you may consider using toProgram

attachAfterComment (Object:node, String:comment, String|Object:str) -> Boolean

Shortcut: Search for given comment, and attachAfter

Parameters:

• node

• comment

• str: String is preferred if not possible remember that only Program can be attached, you may consider using toProgram

Returns:

• Boolean: success

replace (Object:node, String|Object:str)

Shortcut: detach/attach

Parameters:

• node

• str: String is preferred if not possible remember that only Program can be attached, you may consider using toProgram

replaceComment (Object:node, String:comment, String|Object:str)

Shortcut: Search for a comment and replace

Parameters:

• node

• comment

• str: String is preferred if not possible remember that only Program can be attached, you may consider using toProgram

injectCode (Object:tree, Array:range, String|Object:str, Boolean:debug)

Inject code directly intro the given range. After the injection the code will be parsed again so original $id will be lost

Parameters:

• tree

• range

• str: String is preferred if not possible remember that only Program can be attached, you may consider using toProgram

• debug: display $id, $parent and $code in console.log (enumerable=true)

Note: this is dangerous and powerful

transformations

setIdentifier (Object:node, String:new_name)

rename Identifier

Parameters:

• node

• new_name

renameProperty (Object:node, Object:replacements)

traverse and apply given replacements

Parameters:

• node

• replacements

Example:

renameProperty(node, {"old_var": "new_var", "much_older": "shinnig_new"})

renameVariable (Object:node, Object:replacements)

traverse and apply given replacements

Parameters:

• node

• replacements

Example:

renameVariable(node, {"old_var": "new_var", "much_older": "shinnig_new"})

renameFunction (Object:node, Object:replacements)

traverse and apply given replacements

Parameters:

• node

• replacements

Example:

renameFunction(node, {"old_var": "new_var", "much_older": "shinnig_new"})

toProgram (Object|Array:node)

Clone given node(s) and extract tokens & code from root to given you a Program-like attachable node

Parameters:

• node: if array is provided will add all nodes to program.body

tokens

getToken (Object:tree, Number:start, Number:end) -> Object|NULL

Get token based on given range

Parameters:

• tree

• start

• end

Returns:

• Object|NULL

getTokens (Object:tree, Number:start, Number:end) -> Array|NULL

Get tokens in range

Parameters:

• tree

• start

• end

Returns:

• Array|NULL

pushTokens (Object:tree, Number:start, Number:amount)

Push tokens range from start

Parameters:

• tree

• start

• amount

Note: Update nodes range

growTokens (Object:tree, Number:start, Number:end, Number:amount)

Grow tokens in given range

Parameters:

• tree

• start

• end

• amount

Note: Update nodes range

tokenAt (Object:tree, Number:start) -> Object

Get the first token

Parameters:

• tree

• start

Returns:

• Object

addTokens (Object:dst_tree, Object|Array:src, Number:start)

Add src tokens to dst since start (so keep the order)

Parameters:

• dst_tree

• src

• start

Note: Remember to push src tokens before addTokens otherwise won't be synced

replaceCodeRange (Object:tree, Array:range, String:new_text)

Replace code range with given text.

Parameters:

• tree

• range

• new_text

removeTokens (Object:tree, Number:start, Number:end)

Remove tokens in range and update ranges

Parameters:

• tree

• start

• end

Note: Do not remove nodes.

LICENSE

(The MIT License)

Copyright (c) 2014 Luis Lafuente llafuente@noboxout.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.