collection for AST query/manipulation/transformation
npm install sl-esprima-ast-utilsNode module to manipulate, transform, query and debug esprima ASTs.
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.
#### 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] [, Boolean:recursive])
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] [, Boolean:display_code_in_tree])
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:
``js`
renameProperty(node, {"old_var": "new_var", "much_older": "shinnig_new"})
##### renameVariable (Object:node, Object:replacements)
traverse and apply given replacements
Parameters:
* node
* replacements
Example:
`js`
renameVariable(node, {"old_var": "new_var", "much_older": "shinnig_new"})
##### renameFunction (Object:node, Object:replacements)
traverse and apply given replacements
Parameters:
* node
* replacements
Example:
`js`
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.
(The MIT License)
Copyright (c) 2014 Luis Lafuente
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.